Skip to main content

Making docopt and Sphinx work together

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 -- 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:



Labels:

Comments

Post a Comment

Popular posts from this blog

Remove field code from Word document

e.g. before submitting a MS, or hand manipulating some formatting because Word does things (like cross-references) so half-assed [from here ] Select all the text (CTRL-A) Press Ctrl+Shift+F9 Editing to remove anonymous comments that only contain thanks. I really appreciate the thanks, but it makes it harder to find comments that carry pertinent information. I'm also going to try and paste informative comments in the body of the post to make them easier to find.
24 comments
Read more

h5py and multiprocessing

The HDF5 format has been working awesome for me, but I ran into danger when I started to mix it with multiprocessing. It was the worst kind of danger: the intermittent error. Here are the dangers/issues in order of escalation (TL;DR is use a generator to feed data from your file into the child processes as they spawn. It's the easiest way. Read on for harder ways.) An h5py file handle can't be pickled and therefore can't be passed as an argument using pool.map() If you set the handle as a global and access it from the child processes you run the risk of racing which leads to corrupted reads. My personal runin was that my code sometimes ran fine but sometimes would complain that there are NaNs or Infinity in the data. This wasted some time tracking down. Other people have had this kind of problem [ 1 ]. Same problem if you pass the filename and have the different processes open individual instances of the file separately. The hard way to solve this problem is to sw...
Post a Comment
Read more

Reading spreadsheet data in Python: The lack of a good ODS reader

I try and keep long term data in as simple a format as possible, which means text where ever possible. In earlier times I would enter data in excel spreadsheets and then read them from my Python programs using the xlrd package which is excellent. This works well, but in the back of my mind is the thought that someday Microsoft might do something funny with their business model making office software more janky to use and all my fears about keeping data in proprietary formats would come true. Oh, look, that day is today . So, I'm completely abandoning the MS Office suite and going back to basic text files. However, there is a tension between keeping tabulated data in a simple form, such as csv, and entering it in a convenient manner. Excel, of course, nags you everytime you edit a csv file and save it. Libreoffice is excellent: it handles loading and saving in a very streamlined fashion. However, every time you open up the csv file you need to tell Calc what widths you want...
Post a Comment
Read more