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…

Advertisements

11 Responses

  1. […] This post is a continuation to the Sphinx Autodoc Tutorial for Dummies. […]

  2. Hi, thanks, you saved me lot of time… Going through your 2 posts, I could start building the doc for my pkg shortly. Now remain to figure out details…

  3. Hi!
    Thanks for your notes on the doc generation using Sphinx. I have a couple of questions. I’m still trying to make it work with my project and running into troubles. So I thought of asking you.
    My project has many modules and lots of scripts. The directory structure looks something like this:
    |
    |-mbd
    |- Mbd.py
    |-Properties.py
    |
    |-io
    – Adm.py
    – Writer.Py
    |
    |- doc
    – (this is where I’m running the Sphinx make).

    My question is: how do I tell Sphinx that the code is distributed from the top level? What are the content of the code.rst file?
    It seems that code.rst references a python script. What if I have multiple scripts ?
    What should my ..automodule content be?
    .. automodule:: ????
    :members:

  4. Thanks!!! You saved me

    (Dum)Mika

  5. Hello,
    when I run make html I get the following message:
    ” The ‘sphinx-build’ command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the ‘sphinx-build’ executable. Alternatively you may add the Sphinx directory to PATH.
    If you don’t have Sphinx installed, grab it from http://sphinx-doc.org/)

    I added the directory which contains the ‘sphinx-build.exe’ file to my PATH. However the problem continues.

    Any help is appreciated.

    Thanks

  6. Thanks for the simple introduction to using Sphinx.

    FWIW, I’ve adopted a convention of adding a variant of the sys.path.insert() commands in conf.py that you proposed in your Autodoc section:

    sys.path.insert(0, os.path.abspath(‘.’))

  7. […] just in case, here's a great tutorial for getting started with Sphinx and here's the official […]

  8. Hey man thanks for the tutorial ,saved me a lot of headache!

  9. Thanks for the helpful step-by-step explanation!

  10. I LOVE YOU

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: