Skip to main content

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:
  5. 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'))
    
  6. 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().
  7. os.environ['DJANGO_SETTINGS_MODULE'] = 'demo.settings'
    import django
    django.setup()
    
  8. 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.
  9. import redistributable
    
    version = redistributable.__version__
    release = redistributable.__version__
    
  10. Build the documentation issuing make html from the docs folder. 

Comments