Sphinx/Docutils Directive

As of version 0.16.0, Cappa ships with a “docutils” directive capable of rendering the CLI to docutils/sphinx documentation.

In sphinx, you would load this in conf.py, by adding "cappa.ext.docutils" to the list of extensions:

extensions = [
    ...
    "cappa.ext.docutils",
]

The module path to the CLI object is the only required argument. All other options are…optional.

The default configuration is equivalent to:

.. cappa:: <required.module.path.to.Object>
   :style: terminal
   :terminal-width: 0

or with MyST:

```{cappa} <required.module.path.to.Object>
:style: terminal
:terminal-width: 0
```

Options/customization currently include:

  • style: “native” or “terminal” (defaults to “terminal”). “terminal” renders the --help text as it would have rendered at the terminal. “native” renders the CLI structure as native docutils sections/text. Set like :style: terminal.

  • terminal-width: The fixed-width at which to render the terminal-style help text. Defaults to 70. Set like :terminal-width: 80. Note, you can also set the width to 0, to utilize browser line-wrapping, although it will not look identical to the line-wrapping in the terminal.

Customization is likely increase over time purely based off user requests!