Document your Django project using Sphinx documentation tool and reStructuredText
Wednesday, July 28th, 2010So 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 |-settings.py |-urls.py |-templates |-server |---driver.py |---passenger.py |---common.py |---models |------location.py |------mode.py |------person.py |------prefs.py |------trip.py |------reponse.py
Where:
- 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:
export PYTHONPATH=$PYTHONPATH:/home/bodom_lx/Projects:/home/bodom_lx/Projects/dycapo export DJANGO_SETTINGS_MODULE=dycapo.settings |
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
sphinx-quickstart |
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:
dycapo |-settings.py |-urls.py |-templates |-_build |-_static |-_templates |-Makefile |-conf.py |-index.rst |-server |---driver.py |---passenger.py |---common.py |---models |------location.py |------mode.py |------person.py |------prefs.py |------trip.py |------reponse.py
If we generate the documentation right now, using
make html |
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:
.. Dycapo Server documentation master file, created by sphinx-quickstart on Tue Jul 27 17:46:52 2010. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. Welcome to Dycapo Server's documentation! ========================================= Contents: .. toctree:: :maxdepth: 2 Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` |
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 XML-RPC methods ====================== .. automodule:: server.driver :members: |
driver.rst must be referenced from index.rst in some way! This is how we do it: modify index.rst:
.. Dycapo Server documentation master file, created by sphinx-quickstart on Tue Jul 27 17:46:52 2010. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. Welcome to Dycapo Server's documentation! ========================================= Contents: .. toctree:: :maxdepth: 2 driver Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` |
Running again a make html produces the following output:
Sphinx new Index
Sphinx Documentation for driver module
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:
Sphinx Final Documentation Index
Now you should have the basis for documenting your whole project. Browse Sphinx documentation for more information and options.
References
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.
- http://www.toast38coza.com/incomplete-thoughts/setting-up-sphinx-documenter-with-a-django-project-a-quickstart-tutorial
- http://www.meiocodigo.com/2009/03/18/documenting-django-pluggable-apps-with-sphinx/
- http://yml-blog.blogspot.com/2009/06/sphinx-autodoc-and-django-app.html
- http://ericholscher.com/blog/2010/feb/5/large-problems-django-mostly-solved-documentation/
- http://www.rlazo.org/2008/10/24/documenting-a-django-project-with-sphinx/