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

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.

