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

  1. Can you please share source code for this project, because I'm facing lots of problem to integrate this with django.

    ReplyDelete

Post a Comment