A tool to help use the ‘autodoc’ facilties of Sphinx.
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.
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…
… 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
This blog post is based on some work done using : Python 2.6 and Sphinx 1.0.5