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]

3. Run [sphinx-quickstart] 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:

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()].

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.

7. Build the documentation issuing [make html ] folder.