Document your Django projects: reStructuredText and Sphinx

Check this post to learn how to document a Django project!
You’ll get an introduction to the reStructuredText markup language, learn how to install Sphinx, a library that takes the docstrings of your code and compiles them into nice html pages, and configure it for a Django project.

Documenting your project is very important, you know that — that’s why you’re reading this don’t you?
😉

For me, the most important reasons why you should document your projects are:

• It will help you understand what you did — specially a few months after you wrote the code.
• It will help others understand what you did — this way, they can help you improve your code or add some extensions and functionalities.

Here, you’ll learn how to install and use Sphinx, a library that takes the docstrings of your code and compiles them into nice html pages. It’s used to create the official documentation of Python, Django, and most of all other popular Python packages.

But how? How does it compile them into nice pages with headers, links and other common formats? Well, you have to write your docstrings using reStructuredText (frequently abbreviated as reST), a markup format. But don’t worry, that’s easy to learn! 😉

Install Sphinx

Activate your virtual environment and install Sphinx, which is in the Python package Index and can be installed via pip or via easy_install:

$ pip install sphinx

This command will also install the following packages: Pygments, docutils, Jinja2 and markupsafe. Don’t forget to add them into you requirements.txt file. If you have different requirements files for production, developing and testing, I recommend you include Sphinx on the last two (not in production).

Create the docs folder

Now, we will create the docs folder using Sphinx:

$ sphinx-quickstart

Which will ask you different questions. I will show my answers using different colors: blue and red. Make sure you answer the same as me when they are red 😉

Enter the root path for documentation.
> Root path for the documentation [.]: ./docs

You have two options for placing the build directory for Sphinx output.
Either, you use a directory “_build” within the root path, or you separate
“source” and “build” directories within the root path.
> Separate source and build directories (y/n) [n]: n

Inside the root directory, two more directories will be created; “_templates”
for custom HTML templates and “_static” for custom stylesheets and other static
files. You can enter another prefix (such as “.”) to replace the underscore.
> Name prefix for templates and static dir [_]: _

The project name will occur in several places in the built documentation.
> Project name: myproject
> Author name(s): Marina Mele

Sphinx has the notion of a “version” and a “release” for the
software. Each version can have multiple releases. For example, for
Python the version is something like 2.5 or 3.0, while the release is
something like 2.5.1 or 3.0a1.  If you don’t need this dual structure,
just set both to the same value.
> Project version: 1.0
> Project release [1.0]: 1.0

The file name suffix for source files. Commonly, this is either “.txt”
or “.rst”.  Only files with this suffix are considered documents.
> Source file suffix [.rst]: .rst

One document is special in that it is considered the top node of the
“contents tree”, that is, it is the root of the hierarchical structure
of the documents. Normally, this is “index”, but if your “index”
document is a custom template, you can also set this to another filename.
> Name of your master document (without suffix) [index]: index

Sphinx can also add configuration for epub output:
> Do you want to use the epub builder (y/n) [n]: n

Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/n) [n]: y
> doctest: automatically test code snippets in doctest blocks (y/n) [n]: n
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]: n
> todo: write “todo” entries that can be shown or hidden on build (y/n) [n]: n
> coverage: checks for documentation coverage (y/n) [n]: y
> pngmath: include math, rendered as PNG images (y/n) [n]: n
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: n
> ifconfig: conditional inclusion of content based on config values (y/n) [n]: n
> viewcode: include links to the source code of documented Python objects (y/n) [n]: n

A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. ‘make html’ instead of invoking sphinx-build
directly.
> Create Makefile? (y/n) [y]: y
> Create Windows command file? (y/n) [y]: n

This will create a docs folder inside your project folder, containing the files conf.py, index.rst and Makefile, and the folders _build, _static and _templates (which will be empty).

The autodoc extension is needed to import the docstrings of your project files into the documentation.

Create the html files

Inside the docs folder, type:

$ make html

This will create the html pages, which you’ll find in the _build/html folder. Open the index.html file and take a look at what has been created.

You’ll see that the document is essentially empty, as you must indicate sphinx where your project is. So… let’s tell him!

Open the conf.py file (inside the docs folder), and after the lines:

import sys
import os

# 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.insert(0, os.path.abspath(‘.’))

add the following:

sys.path.insert(0, os.path.abspath(‘..’))
from django.conf import settings
settings.configure()

This will tell sphinx where it should look for your project files.

Now, inside the docs folder create a modules folder with a models.rst file inside:

$ mkdir modules
$ touch modules/models.rst

Edit this file and write the following:

Models
======
.. automodule:: myproject.myapp.models
    :members:

Where myproject.myapp.models is the path form the folder that contains the docs folder and your app/models.py. This indicates autodoc that it should read the models.py file looking for docstrings.

However, we still need to include the models.rst file. To do this, open the file docs/index.rst and write:

Contents:
.. toctree::
   :maxdepth: 2

   modules/models

Now, let’s try again with

$ make html

and look at your _build/html/index.html file. You should see a link to Models, containing all the models you have defined there, together with its methods! 😉

Now, you can add as many files you want to document all your project! Moreover, you should learn a little bit more about reStructuredText to make your docs nicer 😉

Don’t forget to share and +1 if useful, thanks! 😉