Setting up Sphinx documenter with a Django project - a quickstart tutorial

Tue, 17 Nov 2009 08:52:21 +0100

Sphinx documenter is quite a nice tool for creating pseudo-auto-documented documentation from your source code. I had a little trouble setting it up, and found that there is fairly poor documentation on the web (a little strange for a documentation tool...). Here's what I did.

1.) Setting it up:

this part is quite easy, just go through the 'getting started' tutorial here

This will create your basic documentation project. You should have a file layout something like this:

Makefile
_build
_static
_templates
conf.py
index.rst

.. and you build your documentation simply using the auto-generated build file:
make html

This will now generate a blank skeleton of your documentation ... not really very useful.

Now what I was interested in is the autotdoc ext. (documentation here). This requires a little extra configuration.

2.) Setting up autodoc

2.1.) Adding some modules

Lets now add some modules for auto-documentation. Lets assume we are have an app called myapp, and we have a models.py module which we want to edit.

In your documentation folder, create a directory called modules, then create a new file called models.rst. e.g.:
mkdir modules
nano modules/models.py

Now edit models.py so that it looks something like this:

myapp.models
==================

.. automodule:: myapp.models
   :members:

now, if we run:
make html

you should get output something like the following:

(test)-bash-3.2$ make html
sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v0.6.3
loading pickled environment... done
building [html]: targets for 0 source files that are out of date
updating environment: 1 added, 0 changed, 0 removed
reading sources... [100%] modules/model
looking for now-outdated files... none found
pickling environment... done
checking consistency... /Users/Me/Projects/MyApp/docs/modules/model.rst:: WARNING: document isn't included in any toctree
done
preparing documents... done
writing output... [100%] modules/model
writing additional files... genindex search
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded, 1 warning.

Note the warning in bold. We need to add a link to our documentation from a page. so .. open up index.rst in your documentation root dir, and add something like this:

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

.. toctree::
   :maxdepth: 2

   modules/model.rst

running it again, you should now get a new error:

/Users/Me/Projects/MyApp/docs/modules/models.rst:4: (WARNING/2) autodoc can't import/find module 'myapp.model', it reported error: "No module named myapp.model", please check your spelling and sys.path

this means we need to set up our django environment, as I learned from this guy. So .. onto the next step:

2.2.) Configuring your django app

We do as above opening my conf.py file, it now looks something like this:

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.append('/Users/Me/Projects/MyApp/src/myapp')
#setup django
import settings
from django.core.management import setup_environ
setup_environ(settings)

.. and finally, we run:
make html

.. and great success, I now have autodocumented modules in my documentation.

Another great and more in-depth resource is this: http://showmedo.com/videotutorials/video?name=2910020

Using Facebook Connect with Yola

Thu, 01 Oct 2009 08:51:49 +0100

I was just on Yola's Get Satisfaction forum and saw a question by a user which I found quite interesting.

The user wanted to integrate Facebook connect with their Yola website. So I wrote a quick tutorial here. Hope it's useful.

incomplete-thoughts

Setting up Sphinx documenter with a Django project - a quickstart tutorial

Using Facebook Connect with Yola

Book Review: The Five Disfunctions of a Team