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.
djhoese
commented
6 months ago
Given an
argparsethat produces an application with the following signature (I leave out the implementation details):Using this extension, the generated documentation from the python definitions will have a structure similar to the following:
Using extensions like
sphinx.ext.autosectionlabel, thecommandheader gets automatically attributed a label that can be referenced as:ref:`command`. The same#commandanchor is also created in HTML for example.If the page where the
.. argparse::directive is included already contained another section namedcommand(with or without an explicit reference label), there is no way to tell Sphinx/RST how to distinguish between the already presentcommandsection and the one generated bysphinx-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 asargparse_prog_commandrather thancommandby itself, allowing documentation to refer to this section explicitly when needed and without conflict with any existingcommandsection header.