Problem of the Day : Generating Sphinx documentation from Python doc-strings

Sphinx : a documentation generator for Python

Problem : Sphinx documentation is not clear (to me) on how to generate documentation from your Python doc-strings. At least, no obvious tutorial exists.

Possibly helpful links ( none of which actually solve this problem )

http://scienceoss.com/use-sphinx-for-documentation/

http://neuroimaging.scipy.org/site/doc/manual/html/devel/guidelines/sphinx_helpers.html

Steps so far :

First, I followed this tutorial to get Sphinx running and installed, and the basic example running. After this tutorial, you should have a working documentation directory that builds a minimal example of "index.rst" and "chapter1.rst"

Second, I tried adding ".. automodule:: numpy" to the top of the demo "chapter1.rst" file. I was pleasantly surprised to see this work, more or less. This inserted some basic numpy documentation into the minimal "chapter1.rst" file. I guess you'd probably have to have numpy installed and working for this to work.

Now what ? I think this means that I need to create a separate ".rst" file in the documentation source directory for every class, module, or source that I want to document.

I also need to figure out how to package my python code into an importable library so Sphinx can see it like numpy. From the Pyhon documentation : A module is a file containing Python definitions and statements. So, I guess each of my .py script files will need a to be turned into a module, and then a separate .rst file for each .py source file will need to be added to my documentation source directory.

All Python source files are automatically modules, with the name of the module as the name of the script file. Sphinx is somehow coupled to the iPython interpreter, I am told. If you can get your modules to be importable form iPython system-wide you'll be all set.

There should be some way to just tell the Sphinx autodoc "here is a python file, please automatically pull documentation out of it". As far as I can tell, there is not. Specifying absolute paths does not work.

This seems to work : add the directories containing your source files to the environment variable "PYTHONPATH". Then, at least the automodule feature will work if you pass it the name of your file ( without the name of extension ).

export PYTHONPATH="~/ahh":$PYTHONPATH

Turns out the the header stuff in the .rst file is necessary, otherwise Sphinx won't generate an entry for your module on the main index page. Also, "toctree" means "table of contents tree" ( I don't think this is explicitly stated in the Sphinx documentation ).

Ok, this is great. automodule seems to work. It looks like you need to manually create a new ".rst" file for every module you want to document, register them in the table of contents tree in "index.rst", then add an automodule command in these files and make sure your file/module is system-wide importable ( in PYTHONPATH ). This isn't exactly what I had in mind when I heard the workd "autodoc", but maybe I can write a script called "autoautodoc" that automates the .. automation ? of ? documentation ??

If you do something like this :

.. automodule:: foo

:members:

all the class files inside the module get displayed as well.

ok... thats nice. I guess I'll go write an auto-autodoc script now.

edit : here is my auto-autodoc scrip, which produces output which can be piped back to bash to perform requisite operations.

import re

files = '''orix
orix.matrix
orix.statistics
orix.device
orix.function
orix.plot
orix.sequence
orix.graph
orix.cpuutil
orix.logic
orix.gpufun 
orix.convolution
'''

print "cd ~/orix/doc"
print "rm *.rst orix.* mods.txt"

files = files.split('\n')

index = '''
Welcome to orix's documentation!
================================

Contents:

.. toctree::
   :numbered:
   :maxdepth: 2
   
'''

for f in files:
    fstring = f+'.rst'
    foo = r'\n'.join([f,''.join(['=']*len(f)),".. automodule:: %s"%f,"    :members:"])
    print 'touch %s'%fstring
    print 'echo -e "%s" >> %s'%(foo,fstring)
    print r'echo -e "%s\n" >> mods.txt'%fstring
    index = index + '   ' + fstring + '\n'

index = index + '''
  
Indices and tables
==================

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

index = r'\n'.join(index.split('\n'))
index = r'\`'.join(index.split('`'))
print 'echo -e "%s" >> index.rst'%index
print 'make clean'
print 'make latex'
print 'make html'
print 'cd _build/latex'
print 'make all-pdf'
print 'xpdf orix.pdf &'
print "cd ~/orix/doc"
print 'firefox ~/orix/doc/_build/html/index.html &'