sphinx-doc / sphinx-doc/sphinx
Custom label for code-block captions (Output 1.2 / Input 1.2 / Source 1.4 / Directory tree 1.2 / etc)
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
Is your feature request related to a problem? Please describe.
Although Listing 1.2 is used in English literature for both source code listing, pseudocode, programoutput, console sessions etc. I would often prefer to use "Output 1.2" when listing output, "Source 1.2" when listing source code etc.
I refer to the Listing in Listing 1.2 as the caption label. This might be the wrong terminology, I don't know. It is of course not to be confused with labels used with references.
Describe the solution you'd like
Input:
.. code-block::
:caption: Output of nested loop.
:caption-label: Output
$ python -V
Python 3.7.4
Output: Output 1.2: Output of nested loop.

Although not the prettiest, the code-block counters could be kept as they were, i.e. no matter the :caption-label: they would use the same counter producing what is in the screenshot.
I suppose the optimal thing would be to use separate counters for each :caption-label:.
Describe alternatives you've considered
I suppose one could use / create special extensions for each use case, extensions which would provide new directives like .. output-block::. This would be semantically pretty, but also a bit overkill in my view, after all it is just a label for the caption, it is not like the block itself should be rendered differently.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
No files, tests, or entry points are identified in the issue. Start by locating Sphinx's code-block caption handling and counter logic, then determine how a custom caption label should interact with shared or separate counters; done means the requested directive option produces the demonstrated label and numbering.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100