sphinx-doc / sphinx-doc/sphinx-argparse

Provide a way to specify a prefix for generated header references

Open
#11 1 comment 0 reactions 0 assignees View on GitHub

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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.