⌨️ Code cell options can have caption

[rowanc1]

We already allow this for options defined with the #| caption: syntax, this expands to being allowed in the code-block options as well.

[changeset-bot]

🦋 Changeset detected

Latest commit: 4e2412c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 5 packages

Name	Type
myst-directives	Patch
myst-transforms	Patch
myst-parser	Patch
myst-roles	Patch
myst-to-html	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[choldgraf]

This looks great! Though I am also confused as isn't this already possible? Here's a screenshot that seems to show a code block with a caption:

https://mystmd.org/guide/code#code-blocks

[rowanc1]

This is code-cell! Not code.

[choldgraf]

Oh nice! I updated the PR title as I think you meant "cell" and that was what confused me. The PR looks good to go from me but I had a quick question for feedback:

When we merge this, it'll auto-populate our docs here right? https://mystmd.org/guide/directives#directive-code-cell

Thinking through the documentation strategy, does this sound correct to you:

• PRs like this should be "auto-documented" as much as possible in mystmd.org, that way we know that all possible configuration options are documented in the mystmd guide. (as is the case with this PR)
• Over time, we should elevate the "reference" section of mystmd.org/guide so that it is easier to discover and these auto-documented tables about directives etc make up the bulk of the docs.
• Over time, we should migrate the "non-reference" content over to Jupyter Book, and the remaining MyST guide content should be more like the "auto-documented tables" along with a "basic usage" example for each directive / role.
• When PRs like this get merged, we should decide whether it's important enough to add to a "how to" example there (in this case, I'd actually suggest we need to document the :caption: flag for code blocks, and assume that users can figure it out for themselves that it works for code cells)

Does that sound right?

[rowanc1]

Yes, docs autoupdate for all directive options.

I have added additional docs about the caption.

The mystmd docs should also be stand-alone from Jupyter Book (i.e. a user coming to mystmd.org can get up and running with the myst cli with the relevant tutorials, without having to know about jupyter book), so there still needs to be some guides and tutorials in the mystmd docs, just more of a focus on reference material over time. This will likely become more clear as JBv2 gets released fully and has more docs focused on building books and how-tos etc.