Rectangle 27 0

README.rst written in reStructuredText and converted to html by rst2ht...

There are multiple options for documenting command line tool written in Python:

  • helpstring shown directly by the command
  • README.rst written in reStructuredText and converted to html by rst2html

(I do not claim, this list is complete)

This is by far the most accessible form of documentation as everyone, who installs the program can show it up.

I highly recommend using docopt for parsing command line, as it brings you best of all - having docstring in your source code (as module docstring) and at the same time on command line.

You can see my post in SO http://stackoverflow.com/a/23304876/346478 or here you see sample from project itself:

"""Usage:
quick_example.py tcp <host> <port> [--timeout=<seconds>]
quick_example.py serial <port> [--baud=9600] [--timeout=<seconds>]
quick_example.py -h | --help | --version

"""
from docopt import docopt


if __name__ == '__main__':
    arguments = docopt(__doc__, version='0.1.1rc')
    print(arguments)
$ python quick_example.py -h
Usage:
  quick_example.py tcp <host> <port> [--timeout=<seconds>]
  quick_example.py serial <port> [--baud=9600] [--timeout=<seconds>]
  quick_example.py -h | --help | --version

There are other argument parsers, like plac or argparse. Personally I like the most docopt.

Writting README.rst is very easy and has advantage, that on github and bitbucket, you get great readable introduction to your project as it gets rendered automatically.

It is also much simpler than Sphinx project, you do not have to use multiple files, have just one.

$ pip install docutils

you get bunch of commands, which let you convert README.rst into something nice. The only command I use from this set is rst2html (on Windows it goes as rst2html.py and you have to play a bit to make it working, but it is definitely worth).

Creation of html for of your README.rst:

$ rst2html README.rst README.html

I do it from my vim editor, where it goes even simpler :!rst2html % %.html what produces README.rst.html file.

I consider Sphinx great extension of reStructuredText and have authored couple of technical booklets with that - it offers great cross referencing syntax, I like it.

But for command line tool I would consider it overkill.

reStructuredText README.rst shall be obligatory part of any Python project regardless of the size, put there all what you think is handy when you forget everything about the project.

On the other hand, I have provided set of pages to my users in html and I am not sure, how often they really read it. People are lazy.

Documentation over help option on command line seems to work best for me. At the moment, you need the help (typing on command line), you have it there. And with packages like docopt it can be perfectly in-line with docstring inside your source code.

And if you want to invest into your users, teach them less (or more) command with those few hot keys to search / for a string, jump to the next occurrence n, back one occurrence N, to the top gg or bottom G. h or H be your friend and q your security break.

thanks for your detailed answer, i allready thought that sphinx is an overkill for this. I figured out that my .rst file had an entry "test module" which caused that the headline in my help was "test module". That's the reason why i thought i have to configure it differently.

How do i generate the README.rst without sphinx? What i want is an overview about the things in my script (classes, methods etc.) and parsed docstrings.

How do i generate a documentation for a 1-file python project (script,...

python python-sphinx