I'm planning to write the documentation of a command line tool as restructuredtext. I'm using Sphinx to render the docs. Beside the html
target I want to use the man
target, in oder to supply docs that can be read in a terminal.
Though I found the relevant configuration variables in the Sphinx documentation, I did not come across hints or example how one would format the documentation sources to achieve a list of options as commonly seen in manual pages as two-column-table.
Are there any guidelines around that cover good practices for html
and man
targets?
Option lists are supported in reStructuredText. See http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#option-lists.
This should work for both HTML and manpage output. There is no special directive; you simply create a two-column table, like this:
-h, --help Show help message and exit
--debug Turn on debug logging
--verbose Turn on verbose output