search

click-contrib / sphinx-click

A Sphinx plugin to automatically document click-based applications
MIT License
212 stars 57 forks source link

Documentation of arguments #22

Open cdeil opened 6 years ago

cdeil commented 6 years ago

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.

stephenfin commented 6 years ago

@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.

girivs82 commented 2 years ago

Just checking if there has been any progress on this issue. Is this happening?

stephenfin commented 2 years ago

No. As noted above, we'd need a PR to work on this