Import command-line documentation from docopt

[alexiswl]

Hello,

I am using docopt for one of my projects to provide a cli-based interface to the package.

The docopt strings are inside classes and have their own syntax.

Is it possible to use sphinx to auto-generate html outputs of the docopt text?

For example -

I have the following class:

class ProjectAnalysesAbort(Command):
    """Usage:
    icav2 projectanalyses abort help
    icav2 projectanalyses abort <analysis_id>

Description:
    Abort an analysis in a project

Options:
    <analysis_id>               Required, the id of the analysis

Environment:
    ICAV2_ACCESS_TOKEN (optional, set as ~/.icav2/.session.ica.yaml if not set)
    ICAV2_BASE_URL (optional, defaults to https://ica.illumina.com/ica/rest)
    ICAV2_PROJECT_ID (optional, set as ~/.icav2/.session.ica.yaml if not set)

Example:
    icav2 projectanalyses abort <analysis_id>
    """

    def __init__(self, command_argv):
      ...

Although this is currently possible, the rendering is not ideal.

When configuring with the sphinx 'autodoc' extension and a simple configuration such as

.. automodule:: icav2_cli_plugins.subcommands.projectanalyses.abort
  :members: ProjectAnalysesAbort

I get something like the following

I would like to be able to:

1. adjust the header class from icav2_cli_plugins.subcommands.project_analyses.abort to projectanalyses abort.
2. Have the two usage options on separate lines
3. Highlight each of the headers: usage, description, options, environment, example

[picnixz]

We do not support docopt which apparently is no longer maintained. One thing I could suggest is to instead use the program directive, though you will not be able to use docopt anymore. Alternatively, you could create your own Sphinx extension but this might be an overkill.

[alexiswl]

Thanks @picnixz, I will try and resist the temptation to develop an extension.

Is it possible in sphinx to just write the docs manually in the rst files. I know this defeats the purpose of tying the documentation to the code, but would at least provide a solution without needing to restructure my code (or write an extension).