Tuesday, September 16, 2014

Sphinx Documentation System

I've started to encourage my son to focus on code that is easier to read by humans.  There are three parts to this:

  1. choose variable, class, and function names that are easy to understand;
  2. break the code into functions and classes instead of one long block and use local variables;
  3. comment the code
For the last part, I started off using pydoc -w filename to extract the docstrings into a document.  This didn't give me as nice a document as I wanted.  I ended up using Sphinx with the autodoc extension

$ sphinx-quickstart

I took all the defaults except for autodoc.
In conf.py, I edited the sys.path

# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.insert(0, os.path.abspath('.'))
I just uncommented the line above.

I then edited index.rst
.. automodule:: main   :members:
I then edited the docstrings in my python main.py file.

No comments:

Post a Comment