docopt to readthedocs / sphinx docstrings

[alexiswl]

While docopt can write great docstrings for the cli, it would be great to showcase their usages on a Readme page somewhere.

[NickCrews]

Are you suggesting that we have some github pages site that holds the documentation? That sounds good to me, but I'm not going to take the time implement it. If someone else puts in the effort though, I'll review!

Closing for now as not immediately planned, but please comment/reopen if you are actively working on it!

[alexiswl]

Are you suggesting that we have some github pages site that holds the documentation?

@NickCrews no, not for docopt itself, but the question related to toolkits that are generated with docopt. Let's say I generate a toolkit using docopt. I would want to then have a plugin to sphinx that can look for docopt based docstrings inside the source directory of that toolkit to generate a readthedocs page for my toolkit. Does that make sense?

[NickCrews]

Sorry, it doesn't. Even more concrete of an example? Are you thinking of a specific project?

[alexiswl]

If I write python code, I can use sphinx to generate the docstrings for a given function from the docstrings inside the function. If I write a commandline tool, I'd like to be able to point sphinx at the docstrings for that commandline tool (the same docstrings that docopt uses to determine the arguments).

[NickCrews]

I'm not that familiar with sphinx, do you mean like a custom domain for docopt? Are you talking about a python API? Can you give some example code of how this API would be used? Can you give example of what the output is?

The raw docstring that is given to docopt is already formatted so that it should be decent documentation if you just inserted it directly into a readme, eg with autodoc. Are you looking to be able to parse the specification so you can render the specification more programatically? Or something else clever with the parsed spec? Or why is the raw docstring that is input to docopt insufficient?

[alexiswl]

Are you looking to be able to parse the specification so you can render the specification more programatically?

Yes, I've tried, see sphinx-doc/sphinx#12406 but the raw docopt docstring is currently insufficient.

[NickCrews]

Ah, thank you, I think that makes more sense. I think this is related to #61. So you would want something like:

docstring = """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>
    """
parsed = docopt.parse(docstring)
parsed

and then what would you want parsed to be?