Django, Sphinx docs and Buildout

Sphinx is a very popular tool used to generate documentation of all sorts. It is used to post-process Python language’s documentation and by a myriad of other projects. Sphinx basically parses files written in restructured text format and outputs html, pdf, e-pub etc.

Although Sphinx might be used for any  docs, it is very well suited for technical stuff, because it is able to automatically generate docs from source code. This is how I use it in my Django projects. In this post I want to share my configuration, and possibly get some feedback on how to improve it :)

Sphinx installation and Buildout

Because I use buildout I use sphinxbuilder recipe in order to make Sphinx commands available in my environment. Typically a developer just has to call

pip install sphinx

or add sphinx to requirements.txt file if using pip (hopefully in virtualenv).

In my case I put sphinxbuilder defaults into my buildout.cfg:

[buildout]
parts = (...) sphinxbuilder

(...)
[sphinxbuilder]
recipe = collective.recipe.sphinxbuilder
source = ${buildout:directory}/docs-src
build = ${buildout:directory}/docs

Don’t forget to check Sphinx tutorial.

Sphinx initialization

After Sphinx is installed the quickstart command should be called:

bin/sphinx-quickstart

or in case buildout is not used call in `docs` directory:

sphinx-quickstart

This will ask some questions, be sure to answer “yes” to:

autodoc: automatically insert docstrings from modules (y/N) [n]

Sphinx configuration

Next thing is to configure Sphinx so that it would be able to find docstrings in Python modules of Django project. In general this requires some tweaking of Sphinx’s conf.py file that is typically located in “docs” directory. Because Sphinx has to find and scan python modules these have to be available in sys.path.

In case of buildout I just copy (this is the ugly part) the sys.path definition from “bin/django” script

import sys
sys.path[0:0] = [
  (...)
  '/home/ext/dev/somefolder',
  '/home/ext/dev/somefolder/project/apps',
  ]

# setup Django
from django.conf import settings
settings.configure()

Documentation

In the last step it is required to update documentation files to include calls to autodoc. It can be done in the following way:
a) create a file `someapp.rst` in docs folder and fill it with:

Some app models
===============
 
.. automodule:: someapp.models
    :members:

Then in index.rst add a reference to it:

Welcome to Someproject's documentation!
========================================

Contents:

.. toctree::
   :maxdepth: 2

   someapp

Build it!
Everyting is prepared so the last thing to do is to call the build command:

bin/sphinxbuild

or in buildout free environment:

make html

The html docs would be generated into `_build` folder.

Summary
So, this is basic setup of Sphinx, buildout and Django that works for me.

Some references:

31. May 2013 by restless_being
Categories: web development | Tags: , , | Leave a comment

Leave a Reply

Required fields are marked *