Apr 9, 2011

Document your Django project using Sphinx documentation tool and reStructuredText

So you wrote a cool documentation in your Python code using docstring and reStructuredText, in order to let other people understand your API. What’s the next step? To export it in html/pdf etc.

I wrote an XML-RPC service providing Dynamic Ridesharing functionalities for my Bachelor Computer Science thesis. It was written using Python and Django. Obviously, I need to document my XML-RPC methods for people that will write clients, therefore an API is needed.

Many tools for exporting Python documentation exist, but the most comfortable one for Django seems to be Sphinx. As I said, it seems. Because none of those tools are explicitly written for Django projects. There are some posts around that seem to teach you how to use Sphinx for document your Python Django project and therefore export API. However, I feel stupid as I could not fully understand any of them. So here I am writing a tiny how-to for exporting the documentation of a Django project using Sphinx, docstring and reStructuredText.

Note that this is neither a reStructuredText nor a Sphinx tutorial, as their respective websites are clear enough. I suppose you already have Sphinx installed and your code is already documented. Also, this is for Gnu/Linux and Mac Os X (should work on *BDS too).

Ok, let’s imagine that we have a Django project with the following (not very common) skeleton:


  • dycapo is the project name/folder
  • server is an application of the project
  • driver.py, passenger.py, common.py are the modules holding the functions we want to document
  • models contains Django’s splitted models for server application

Yeah, the example is taken from my project. I’m using it because it has some non common things such as functions defined outside views.py and splitted models.

Open the terminal. First, we set some environment variables:

From now on, don’t close the terminal or you will loose the below defined variables.

Be sure to change the values to fit your needs. Then, following Sphinx quick start tutorial, go to your project folder (it would be /home/bodom_lx/Projects/dycapo for me) and use

Like the tutorial says, answer the questions and be sure to say yes to the “autodoc” extension. Sphinx adds three new directories and three new files to your project’s root:

If we generate the documentation right now, using

Something will be created in directory _build/html. Here is a screenshot:
Sphinx Default Generated Documentation

Impressive. But completely empty. Module index link is broken, nothing else works. Ok, let’s add something to our documentation!
Sphinx master file has been generated by sphinx-quickstart command. It is our index.rst file. Let’s take a look at it:

Do you notice the correlation between this file and the screenshot?

We will now add the documentation for the functions contained in server/.
Create a new file in the root of your project, called driver.rst. We will now add the code for documenting server/driver.py

driver.rst must be referenced from index.rst in some way! This is how we do it: modify index.rst:

Running again a make html produces the following output:

Not bad for having written quite nothing! The same can be achieved for server/common.py, server/passenger.py and server/models by creating the corresponding .rst files and then including them in index.rst under driver.

Final result:

Now you should have the basis for documenting your whole project. Browse Sphinx documentation for more information and options.

Below are the posts I found when searching for how to export documentation for a Django project. My post also takes something from all of them.

written by dgraziotin

Dr. Daniel Graziotin received his PhD in computer science, software engineering at the Free University of Bozen-Bolzano, Italy. His research interests include human aspects in empirical software engineering with psychological measurements, Web engineering, and open science. He researches, publishes, and reviews for venues in software engineering, human-computer interaction, and psychology. Daniel is the founder of the psychoempirical software engineering discipline and guidelines. He is associate editor at the Journal of Open Research Software, academic editor at the Research Ideas and Outcomes (RIO) journal, and academic editor at the Open Communications in Computer Science journal. He is the local coordinator of the Italian Open science local group for the Open Knowledge Foundation. He is a member of ACM, SIGSOFT, and IEEE.

  • Rohit Agarwal Nov 23, 2011 Reply

    Thanks a lot! I was stuck on this for sometime and the submission date of my project was coming very near. It saved me!

    • dgraziotin Nov 23, 2011 Reply

      Glad it helped you, even if it misses many screenshots that I unluckily lost on a black day.

  • Naoko Sep 9, 2012 Reply

    Thank you very much. I was keep getting import error… though I see some posts / tutorial says all I need is to append to sys.path in conf.py. as if conf.py is not read before $ make html
    but all is working now. thank you again!

  • alswl Dec 12, 2012 Reply

    Thanks for your post. ‘export DJANGO_SETTINGS_MODULE=dycapo.settings’ helps me a lot.

  • Derek Dec 13, 2012 Reply

    Great “quick start”. Any chance you could add on to this, or perhaps follow-up with an example showing how you would expand the documentation with other .rst files that are not generated by Sphinx but added manually (say, “how to” guides etc.) Where would these go? How would ypu add them to the system etc.

  • Rafael Sep 5, 2014 Reply

    Nice and easy thanks.

Leave a comment