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

• 2 min read

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.