How do i generate a documentation for a 1-file python project (script, no module) with sphinx?

Question

I have a python project which is stored in one file, it's a command line tool.

I've managed to generate a documentation with sphinx allready, but how do i determine that my file is a script and not a module?

Answer 1

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
• Sphinx documentation

(I do not claim, this list is complete)

helpstring printed from command line

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 https://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)

When running from command line:

$ 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.

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

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.

When you install docutils:

$ 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.

Sphinx documentation

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.

For description how to use Sphinx, refer to their great documentation.

Conclusion

Sphinx is great, but seems to be overkill for command line tool.

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.

Enjoy living on command line.