Setting up Sphinx Documentation with Django

Having generated my first few real applications in Django, it became obvious there was at least one glaring omission to my development process – documentation!

I knew there were various solution to this problem, but after DjangoCon 2011 there was only one solution that seems to be talked about seriously – Sphinx.

Initial reading of the documentation and tutorials left me a little bewildered. However, after I managed to successfully setup and make my first html docs, it all seemed a little more straightforward. To help clarify this process for myself and anyone else in a similar situation, here are the steps I took.

Note: I am using Ubuntu linux. Process may differ for Mac/ Windows

        1. Install sphinx using
          $ easy_install sphinx
        2. Navigate to your project directory and run
          $ sphinx-quickstart
        3. Answer all questions. Importantly, answer yes to
          autodoc: automatically insert docstrings from modules (y/N) [n]:
        4. This should produce a directory structure like so:
          • Makefile
          • _build
          • _static
          • _templates
          • index.rst
        5. Now we can run
          $ make html

          to create the first version of our docs. This will create the _build/html directory containing the html files

        6. Open index.html in the browser and you should see your empty (for the moment) project docs
        7. Now, to make use of the handy autodoc extension, we need to make sure is setup properly. First check that the autodoc extension is enabled:
          # Add any Sphinx extension module names here, as strings. They can be extensions
          # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
          extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.pngmath', 'sphinx.ext.viewcode']

          Then edit the file to include the path and Django project settings:

          # documentation root, use os.path.abspath to make it absolute, like shown here
          sys.path.insert(0, os.path.abspath('.'))
          # setup Django
          import settings
          from import setup_environ
        8. Now we can test this by referencing our first module. Create another directory called /modules in the project root and created models.rst to reference my module in my app. In this write:
          .. automodule:: myapp.models
        9. Now in index.rst we can add a reference to this module:
          .. toctree::
          :maxdepth: 2
          Indices and tables
          * :ref:`genindex`
          * :ref:`modindex`
          * :ref:`search`
        10. The autodoc extension should automatically extract information and comments about the models from models.
        11. Run
          $ make html

          again and refresh the docs in the browser. Now there should be section entitled models and page listing the classes, fields and comments of your module

        12. From here you can explore some of the further options in autodoc such as:
          .. automodule:: myapp.models

Some useful links:

2 thoughts on “Setting up Sphinx Documentation with Django

  1. Pingback: Django, Sphinx docs and Buildout | Restless Being

  2. Worked perfect for me… đŸ™‚ Thanks a lot !! Was struggling with it since day or two with documentation. Followed your steps and it worked just fine for me. Hope it does for other’s as well.. Good work Keep Going …

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s