How to Integrate Sphinx with a Django Project for Automatic Documentation Generation

A few points on integrating Sphinx with a Django redistributable project for generating documentation embedded in the source files.

1. Project directory structure should look like this:
   

   django-redistributable/
     demo/
       demo/
         settings.py
         urls.py
         wsgi.py
       templates/
       manage.py
     docs/
       conf.py
       index.rst
       Makefile
       make.bat
     redistributable/
       models.py
       views.py
       templates/
       static/
     tests/
     setup.py
     MANIFEST.in
     README.rst
     LICENSE
     requirements.txt
   

2. Install sphinx and sphinx-autobuild using pip.
3. Run sphinx-quickstart from the docs folder. Provide default answers for all prompts.
4. Edit docs/conf.py such that the redistributable package and the demo project's apps are importable from the docs folder. At the top of the conf.py file:

import os
import sys
import django

sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
sys.path.append(os.path.join(os.path.dirname(os.path.dirname(__file__)), 'demo'))

5. Setup sphinx such that it can safely import the Django source file referred to in any RST files for autodoc. For this you need to setup the DJANGO_SETTINGS_MODULE environment variable to demo project's settings. Also need to initialize Django's AppRegistry with a call to django.setup().

os.environ['DJANGO_SETTINGS_MODULE'] = 'demo.settings'
import django
django.setup()

6. Embed the package version in the redistributable folder's __init__.py file as __version__ = "x.y" and then import this version into conf.py. This will make the package version and documentation version concurrent.

import redistributable

version = redistributable.__version__
release = redistributable.__version__

7. Build the documentation issuing make html from the docs folder.