Tweet

Automating sphinx.ext.autodoc

A tool to help use the ‘autodoc’ facilties of Sphinx.

Summary

Sphinx has a great extension,sphinx.ext.autodoc, which imports the modules you want to document and uses the docstrings as the basis for the documentation. A script I’ve just found makes using sphinx.ext.autodoc even easier.

generate_modules.py

Although the sphinx.ext.autodoc extension reduces the work of creating Sphinx source files a great deal I still found myself having to create a set of files which corresponded to the modules in a project. This was a bit of a bore particularly as I like to start creating documentation early in a project and so modules would come and go during development.

On a number of occasions I wished I had a script to automatically create the source files needed … well it turns out that Etienne Desautels has already done the heavy lifting and written generate_modules.py which does just what I want.

Making use of it

generate_modules.py is completely independent of Sphinx. Just download it from the above location and run it as

>python generate_modules.py --help

Usage: generate_modules.py [options] <package path> [exclude paths, ...]

Note: By default this script will not overwrite already created files.

Options:
 -h, --help            show this help message and exit
 -n HEADER, --doc-header=HEADER
                       Documentation Header (default=Project)
 -d DESTDIR, --dest-dir=DESTDIR
                       Output destination directory
 -s SUFFIX, --suffix=SUFFIX
                       module suffix (default=txt)
 -m MAXDEPTH, --maxdepth=MAXDEPTH
                       Maximum depth of submodules to show in the TOC
                       (default=4)
 -r, --dry-run         Run the script without creating the files
 -f, --force           Overwrite all the files
 -t, --no-toc          Don't create the table of content file

Most of this is pretty self-explanatory.

My index.rst looks like this :

Welcome to pySourceAid's documentation!
=======================================

Contents:
=========

.. toctree::
:maxdepth: 2

overview.rst

Modules
===============

.. toctree::
:maxdepth: 20
:numbered:
:glob:

modules/*

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

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

And that line in the index.rst…

    modules/*

… means that autodoc is going to go looking for source files corresponding to each of the modules in a directory called modules. As a result when I run generate_modules.py I use a command like this

python generate_modules.py --suffix=rst --dest-dir=C:\myproject\docs\source\modules C:\myproject\src

Where the modules are living in C:\myproject\src

Environment

This blog post is based on some work done using : Python 2.6 and Sphinx 1.0.5