search

jazzband / docopt-ng

Humane command line arguments parser. Now with maintenance, typehints, and complete test coverage.
MIT License
177 stars 20 forks source link

docopt to readthedocs / sphinx docstrings #68

Open alexiswl opened 1 month ago

alexiswl commented 1 month ago

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

NickCrews commented 1 week ago

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 commented 1 week ago

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 commented 1 week ago

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

alexiswl commented 1 week ago

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 commented 1 week ago

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 commented 1 week ago

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

Yes, I've tried, see https://github.com/sphinx-doc/sphinx/issues/12406 but the raw docopt docstring is currently insufficient.

NickCrews commented 6 days ago

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?