I use docopt to build simple, self-documenting command line interfaces to scripts. I was delighted when sphinx's outdoc features seemed to interpret docopt's options well:
But it is apparent that the formatting of the usage part is a bit off and any option that does not begin with
It turns out that Sphinx has a bunch of plugins for documenting command line options with sophisticated ones able to run the code or analyze the argparse object itself but nothing for docopt. One code sample I found wrote out the command line description in restructured text and then stripped out parts of it to make docopt parse it properly
The real solution is, of course, to write a Sphinx extension for docopt, but I ended up using a slight modification that doesn't confuse docopt and lets SPhinx make decent (not great) autodoc out of it.
My docstring looks like this:
And the Sphinx documentation looks like:
But it is apparent that the formatting of the usage part is a bit off and any option that does not begin with
--
or -
messes up the options formatting completely.It turns out that Sphinx has a bunch of plugins for documenting command line options with sophisticated ones able to run the code or analyze the argparse object itself but nothing for docopt. One code sample I found wrote out the command line description in restructured text and then stripped out parts of it to make docopt parse it properly
The real solution is, of course, to write a Sphinx extension for docopt, but I ended up using a slight modification that doesn't confuse docopt and lets SPhinx make decent (not great) autodoc out of it.
My docstring looks like this:
Command line:: Usage: fasta2wg --index=IDX --wg=WG [--fa=FA] [-v] fasta2wg describe --wg=WG Options: --index=IDX Index file (.json) listing fasta files to be inserted into whole genome --wg=WG Name of whole genome file --fa=FA If set, will also dump a fa.gz file (by simply concatenating the files together) for use by BWA -v Be verbose when you do things describe Take the indicated whole genome file as input and print a summary of what it contains
And the Sphinx documentation looks like:
Comments
Post a Comment