Skip to content

Support numbered code-block references *without* :caption: #114

@rossbar

Description

@rossbar

Is your feature request related to a problem? Please describe.
Not so much a problem as a limitation of sphinx for scientific publication. Setting numfig=True in the conf.py enables automatic numbering of things like figures, tables, code-blocks, etc. Unfortunately, for code-blocks this only works if the :caption: has been defined.

Describe the solution you'd like
For scientific publication, it would be very nice if it were possible to reference a code block via numref without explicitly having to define a caption: within the code-block directive. For example:

I want to reference the following code-block with a numref:
```{code-block} python
---
name: my-code
---
print("Hello World")
```
But when I use try to reference via {numref}`my-code`, it fails unless there is a caption.

Note that the desired behavior (numref without caption) works find for tables and figures.

Describe alternatives you've considered
Pre-labeling code-blocks doesn't work either:

(my-code)=
```{code-block} python
def foo():
    pass
```
Referencing the code-block like {numref}`my-code` doesn't work either

Additional context
Note that this is a limitation of sphinx, not the myst-parser. The myst-parser output is entirely consistent with rST output with sphinx (i.e. warnings and failed xrefs). Perhaps this is something that needs to be fixed upstream in sphinx, not in MyST (let me know if that's the case).

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestupstreamThis issue requires an upstream dependency fix

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions