sphinx-doc / sphinx-doc/sphinx-argparse
Provide a way to specify a prefix for generated header references
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 38
- Forks
- 33
- PR merge metrics
- No merged PRs in 30d
Description
Given an argparse that produces an application with the following signature (I leave out the implementation details):
prog --opt command
Using this extension, the generated documentation from the python definitions will have a structure similar to the following:
-------------------
Optional Arguments
-------------------
~~~~~
--opt
~~~~~
some description
-------------------
command
-------------------
Possible choices: cmd1, cmd2
~~~~~
cmd1
~~~~~
[...]
~~~~~
cmd2
~~~~~
[...]
Using extensions like sphinx.ext.autosectionlabel, the command header gets automatically attributed a label that can be referenced as :ref:`command`. The same #command anchor is also created in HTML for example.
If the page where the .. argparse:: directive is included already contained another section named command (with or without an explicit reference label), there is no way to tell Sphinx/RST how to distinguish between the already present command section and the one generated by sphinx-argparse. Since documentation often has to refer to the same concepts and the "command" offered by the CLI, it is not unlikely to have the same headers defined somewhere else.
It would be useful for this extension to provide some sort of :ref-prefix: parameter that would be applied to all sections generated by it.
For example, providing :ref-prefix: argparse_prog_ to .. argparse:: would generate the anchor reference as argparse_prog_command rather than command by itself, allowing documentation to refer to this section explicitly when needed and without conflict with any existing command section header.
Contributor guide
No contributing guide indexed for this repository
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
The issue names the .. argparse:: directive but no files or tests; locate its implementation and the code that emits generated section references. Trace how section titles become labels, then verify that a :ref-prefix: option is applied to generated sections without changing existing behavior. Done means the generated command anchor includes the prefix and avoids conflict with an existing command section.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100