What would be simplest way to add CLI help reference into sphinx documentation?

[Tobi-De]

Hello there, I hope you are doing great.

If I need to include the help message of my commands automatically inside a sphinx documentation, or generate documentation from my cli app, what are my options ?

[DanCardin]

pawamoy had a similar usecase, but for mkdocs: #69. Wherein he produced markdown from the cli structure and presumably exec'd the result somewhere else, although i can't say the details.

Since it's come up twice in a relatively small sample set of people, i'd be interested in a first-class feature for supporting the usecase, but it's not obvious to me at this point what form that would take. Perhaps at least for sphinx that'd mean a sphinx plugin.

[Tobi-De]

There is a lot of good options available for mkdocs and markdown (ex: https://github.com/ewels/rich-codex), but I can't find what I want with sphinx and rst, there is https://github.com/WhyNotHugo/sphinx-autorun but it ia barely maintained and do not produce colored output 😞

[pawamoy]

You can probably rework the snippet in #69 as a custom Sphinx directive. Add a cappa_cli.py module in your docs folder, make sure it's exposed in Python's sys.path (by adding the docs folder to it in conf.py for example), and add "cappa_cli" to the extensions list in conf.py.

docs/
    conf.py
    cappa_cli.py

extensions = [
    "cappa_cli",
]

In cappa_cli.py, register your directives like so:

from docutils.parsers.rst import Directive


class CappaCli(Directive):
    ...


def setup(app):
    app.add_directive("cappa_cli", CappaCli)

The docs will explain what to put in CappaCli better than I would.

Then you can inject your CLI docs in a rST document with this:

.. cappa_cli::
    :cli_class: package.module:CappaDataclass

.. the option above just shows what the directive could accept

(You might already know all this, just writing for reference)

---

Looking at the above, it's probably not the simplest way. Maybe you could also use the programoutput extension, though I think you'd have to output HTML directly, which is not great.

[DanCardin]

I've started looking into a sphinx directive I could ship with the library. seems worth, even to my own docs.

[DanCardin]

@Tobi-De #89. If you have a chance, ideally you could try this out before I merge it.

[Tobi-De]

@Tobi-De #89. If you have a chance, ideally you could try this out before I merge it.

Nice, I will

[Tobi-De]

I might be doing something wrong, but right now it shows nothing

Start project
=============

.. cappa falco.commands.StartProject

the sphinx build command shows not errors, the extensions is loaded but the directive does nothing
I'm testing it agains this repo https://github.com/Tobi-De/falco/blob/main/docs/the_cli/start_project.rst
https://github.com/Tobi-De/falco/blob/main/src/falco/commands/start_project.py (the command I tried)

[Tobi-De]

my bad, there is something missing in my directive, I copied it from yours docs, so it is missing there too, the correct syntax is

.. cappa:: falco.commands.StartProject