Sphinx Autodoc Tutorial for Dummies

I recently installed Sphinx and spent the better part of a day trying to get it to work. And not because it was hard (it actually came with a “d’oh!” moment at the end), but rather because I found the Sphinx tutorial rather obscure. This tutorial is going to show how to use Sphinx to autodocument your modules.

It’s actually really easy. Follow these steps, and you can’t go wrong.

Install Sphinx.

easy_install -U Sphinx

easy_install comes with the Python installation (2.7) and can be found in the Scripts subfolder (C:\Python27\Scripts). This is also where the sphinx-quickstart script will be added.

Create a documentation directory.

Get started by running

sphinx-quickstart

You’ll enter a number of options now. In most cases you can simply click ENTER, and Sphinx will select the default options. I’ve highlighted some things you want to pay attention to:

• Root path for the documentation. Where you want your files to be. I created a “docs” subfolder in my main project, so it doesn’t clutter up my project.
•  autodoc: automatically insert docstrings from modules (y/N) [n]: Click Yes Here
• Be sure to create a makefile. It makes life simple.

You can pretty much go with the default options, other than autodoc. Sphinx will generate an empty project in the path you specified, with a default index.rst file. This will be the root of your project – all other files will be accessed through it. At this point, the basic structure already works. Compile it by running the makefile generated by the sphinx-quickstart script.

make html

The generated html files will be in your specified path/_build/html.

Autodoc, roll out!

In order for sphinx to be able to document your python code, it needs to find it first. Open the generated conf.py file in your specified path. Add the following line (with the path of your Python source). Make sure to use Python string formatting as shown!

sys.path.insert(0,"C:\\workspace\\PyPlotStatistics\\src")

You can also use the following notation for a relative directory. abspath will make the path absolute and fix up the formatting as well.

os.path.abspath('mydir/myfile.txt')

Adding notation

Open index.rst. The blank file should look like this:

Contents:

.. toctree::
   :maxdepth: 2

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Add the name of one of your python modules and an example class, located in your specified source path. The index file should look like this:

Contents:

.. toctree::
   :maxdepth: 2

.. automodule:: SomeModuleName

.. autoclass:: SomeClassName
    :members:

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Run make html again to rebuild. Sphinx should automatically identify your module and add a reference to SomeModuleName and SomeClassName. These references will also appear in the index. The clause :members: specifies that all members of the class will be documented, so you don’t have to write in each function manually.

Expanding the Table of Contents

At this point you can add other files and modules to create the documentation the way you like. Make sure all additional files are in the format you specified (default is *.rst), and in your sphinx documentation directory. For instance, if you were to move your module documentation into a file called code.rst, the expanded index might look like this:

Contents:

.. toctree::
   :maxdepth: 2

   installation.rst
   code.rst

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Troubleshooting

Python modules / files don’t appear in the documentation.

1. Sphinx documentation works with alignment. Make sure the indentation is exactly as shown in both previous examples, so that all the items in the table of contents are exactly aligned. This is an easy one to miss.
2. Check the path in sys.path, maybe by printing it out yourself. Is the formatting correct? Is the path accurate?
3. Have you typed in the module / class name correctly (case and all)?

I can see my class, but it doesn’t show any / some of the functions.

Function documentation should look like the example and be indented properly as well, otherwise sphinx won’t recognize it.

"""
Created on 29 July 2012
@author: Lisa Simpson
"""

class DatabaseManager(object):
    """
    Create and manage a new sqlite database.
    """

I don’t feel like putting in all my files manually!

Neither do I! The next section is for you…

Saving Time With APIdoc

APIDoc is a tool that comes with sphinx and is designed to automatically pull documentation out of your entire project, automatically creating *.rst files for each module. You can find the apidoc scripts in the Python2X/Scripts directory with the other sphinx scripts.

sphinx-apidoc [options] -o <outputdir> <sourcedir> [pathnames ...]

Options and pathnames are optional, but the full explanation of all the options can be found in the sphinx apidoc documentation. Apidoc is a simple script which instantly generates all your project documentation.

Numpydoc

Tutorial expanded! Learn how to add numpydoc to Sphinx, and what it gives you…