Click: Document CLI in sphinx with a sphinx extension

[Diaoul]

I see you are using sphinx directives to run some code and document your examples, any chance you could make that a sphinx extension for mere mortals that want to document their own CLI with sphinx?

Or is there a better way to integrate cli --help within a sphinx documentation?

[Diaoul]

Related to #255, discussed in https://github.com/mitsuhiko/click/issues/127#issuecomment-45338536 and https://github.com/mitsuhiko/click/pull/234#issuecomment-73091167.

Isn't most of the work already done with clickdoctools.py?
Edit: Nevermind, this is OK to display --help output but it would be better to have a nicely reStructuredText formated text generated from the command.

[untitaker]

If anybody creates such an extension, it'd be nice to have it on https://github.com/click-contrib

[meejah]

I did hack something like this together at one point, but it would take some (probably non-trivial) amount of work to make it good enough for "real" use. If someone is interested in doing that, I can find it -- I don't have time in the immediate future...

[pwm1234]

I second the request for a nice way to document a click application. Click is quite nice, but now that I have to write a "User's Guide" kind of document for my click application, I am struggling to find a way to keep the documentation current with the application arguments and usage text.

[t-8ch]

I have written something like that. I just stupidly prints the --help messages recursively though.

This sphinx extension: jiffyboxdoctools.py

With this invocation:

.. jiffybox:click-help:: jiffybox

Yields:
http://python-jiffybox.readthedocs.io/en/latest/cli.html

(Currently GPL3, but it should be possible to make it BSD)

[rbonthond]

I'm using https://pythonhosted.org/sphinxcontrib-programoutput/, so I can do ".. command-output:: mycli cmd --help" in my documentation.

[tony]

The --help by itself isn't enough for me imo.

I'm switching from argparse to click in a few projects. The standard library argparse thing I used was https://github.com/ribozz/sphinx-argparse. So it looks like I need something to replace that for click.

Example output: https://sphinx-argparse.readthedocs.io/en/latest/sample.html

[stephenfin]

I have this done in sphinx-click. I think that should satisfy most requests. @untitaker hoping I can get it moved to click-contrib.

[stephenfin]

I also noted that someone started work on this for sphinxcontrib.autoprogram but it never got in :disappointed:

[rbonthond]

@stephenfin sphinx-click looks great, awesome!

[jcrotts]

sphinx-click was added to click-contrib, and seems like it will handle most use cases. If there is a need for additional work please open a new request.