Adding Sphinx Documentation to a Django Project

I hand not used Sphinx to generate documentation for a Django project before. Unfortunately I found the documentation web to be in the no man’s land between cryptic and sparse. After a number of mistakes, I was successful in producing auto-generated documentation from the Python code.

These are my notes for creating a basic set of documentation derived from the source code.


I would prefer to keep all of Sphinx’s files in a subdirectory relative to the project root, but it appears to my untrained eye that Sphinx requires its configuration file and root document in the project root. Sphinx was happy to put its intermediaries and final product into a subdirectory, however.

Initial Installation

Running the Sphinx configuration script was straightforward. By default the autodoc (automatic documentation generation) is not enabled. Be sure the answer “y” to it.

Because I was trying (unsuccessfully) to get Sphinx to operate exclusively out of a subdirectory, I had to manually move the and index.rst files to the project root, then hack the config file so that templates_path, exclude_patterns, and html_static_path contained the subdirectory path.

Only at this point was I able to perform a build on this bare-bones set of documentation.

Overall Hierarchy

The structure that I got to work was a Sphinx index.rst file in the project root and every Python package directory. This forms a tree of index.rst files corresponding to packages.

Contents of the index.rst File


Every index.rst file must contain a header. For example:



Each index.rst file contains the following if the package contains a sub-package:

.. toctree::
    :maxdepth: 2


Indentation is significant in a Python sense. Additionally, blank lines are significant.


Each index.rst file contains the following for each Python module in the same directory as the index.rst file:

.. automodule:: {full Python module name}

Remember to ensure this is isolated from its neighbours by a blank line.

The autodoc process actually loads the Python module to perform introspection. From what I understand in the Sphinx documentation the full Python module name is required. For example, given the following file hierarchy:


The Sphinx file package1/index.rst would contain:

.. automodule::

The Sphinx file package1/package2/index.rst would contain:

.. automodule::

Non-Generated Documentation

Documentation that is not automatically generated can be kept in subdirectories and included in the ..toctree:: section in the same manner as sub-package .rst files are.


I encountered a nice write-up here, which includes much more helpful information that I provide in these notes.

This entry was posted in Programming and tagged , , , , , . Bookmark the permalink.

One Response to Adding Sphinx Documentation to a Django Project

  1. Tomas says:

    Thanks for the tutorial but what if I am using django translations? It throws encoding error. See the full question: . I really need to solve this. Thank you for any advice.

Leave a Reply