sphinx-click
sphinx-click copied to clipboard
click-contrib
Documentation of arguments
Currently you document command like this (see here):
.. program:: cli (including help text)
.. code-block:: shell
.. rubric:: Options
.. rubric:: Arguments
Click in the console help output documents commands like this
Usage (corresponding to your shell code block)
Help text
Options
Click docs at http://click.pocoo.org/dev/arguments/ say
Click will also not attempt to document arguments for you and wants you to document them manually in order to avoid ugly help pages.
and expects arguments to be documented in the help text. Given that arguments don't support a help the argument docs you are generating doesn't really contain much useful information.
How about removing arguments docs completely, i.e. follow the lead of click for the help page?
Or if you want to keep it: how about putting the argument description before the options, i.e. closer to where arguments are usually described for click commands, and add a config option for click-sphinx users to select if they want to emit the arguments rubric (for me it would be no, I would like to not have it)?
A more minor question / change request I have is whether it would be better to put the command help text after the usage line. This is then how click and man pages in general do it, and what I find most readable to have the usage line at the top.
@stephenfin - Let me know what you think. If you agree with any of the suggestions I'd be happy to make a pull request.
@cdeil The best way to approach this is with a PR. I'm pretty sure I borrowed the layout from click-contrib's brethren, sphinxcontrib-autoprogram. Ideally, I'd like to make this configurable. Perhaps a hide_args option, both globally and per-directive? Alternatively, a show_args option that defaults to True now but emits a warning if not manually configured. We can then modify this to default to False in a future release.
Just checking if there has been any progress on this issue. Is this happening?
