Question: Support for generic parameters in code-cell directive?

[rossbar]

I'm not sure whether this is the right place to ask, so please bear with me!

I find myself using the {code-block} directive quite often to illustrate code examples. One particularly nice feature is the seamless integration of things like labels and references with sphinx. For example, I can do something like:

```{code-block} python
---
caption: 'My caption'
name: 'code:my_example'
---
def my_code_here():
    pass
```

Then subsequently reference the block like {numref}`code:my_example` in the text cross-reference the code block. I am curious if there is (either currently or planned to be) support for these generic parameters (name: and caption:) in the code-cell directive. It would be great if there were a directive that behaved just like {code-block} does, but includes the additional functionality of being executable as well.

I was looking through the MyST-NB docs and didn't see anything related to this - if I've missed something (or am looking in the wrong place) please let me know!

[choldgraf]

Interesting - nope we don't have this support right now, but I think the way we could do it is:

1. When we create the notebook w/ jupytext, add these extra parameters as cell metadata somehow
2. Add rules for using that cell metadata in the Sphinx parser for ipynb files

[rossbar]

Cool! I think trying to match the name parameter at least (to hook into the cross-referenceing machinery which is already in place) would definitely be nice.

In principle the pattern could be expanded to support both code cells and their outputs, providing a nice shorthand for/alternative to the glue mechanism. For example, if you had a cell that created a plot:

```{code-cell}
---
input:
  name: code:my_plot
  caption: 'This is the code that produces my figure'
output:
  name: fig:my_plot
  caption: 'This is my figure'
---
plot(my_data)
```

A pattern like this would allow the author to be able to independently reference both the cell itself and it's output (i.e. the generated figure) independently in the text, without the need for adding any glue() to the code itself.

Of course, you'd have to be careful with an approach like this so as not to get too heavy on the metadata, but IMO it would be a nice feature.

[akhmerov]

Should the figure caption support markup? It would make sense that it should (e.g. using math in the figure caption is quite common). That, on the other hand, would mean that the directive attributes need to be accessible to the parser, if the figure caption is to be provided via cell parameters.

[rossbar]

Should the figure caption support markup?

Ideally, yes - the options for the MyST directives do, and it would be great if the {code-cell} directive could support the same (or at least a reasonable subset of) the features that are supported by e.g. {code-block}, {figure}, etc. As I understand it, the {code-cell} directive and these other components are parts of separate packages (myst-nb and the myst-parser, respectively) so I have no idea how difficult it would be to support something like this. From a user/author perspective I think it would be a very nice feature.

[chrisjsewell]

Note, this is essentially a duplicate of #72

[rossbar]

Note, this is essentially a duplicate of #72

With almost a complete overlap and duplication of the discussion - thanks for pointing this out!

[choldgraf]

sooo do folks mind if I close this one? :-)

[chrisjsewell]

@rossbar see https://myst-nb.readthedocs.io/en/latest/use/formatting_outputs.html#images 😄

So I'm going to close this, but feel free to open any more specific issues about supporting certain parameters (like for inputs cells)