Setting up Sphinx Documentation with Django

Having generated my first few real applications in Django, it became obvious there was at least one glaring omission to my development process – documentation!

I knew there were various solution to this problem, but after DjangoCon 2011 there was only one solution that seems to be talked about seriously – Sphinx.

Initial reading of the documentation and tutorials left me a little bewildered. However, after I managed to successfully setup and make my first html docs, it all seemed a little more straightforward. To help clarify this process for myself and anyone else in a similar situation, here are the steps I took.

Note: I am using Ubuntu linux. Process may differ for Mac/ Windows

        1. Install sphinx using
          $ easy_install sphinx
        2. Navigate to your project directory and run
          $ sphinx-quickstart
        3. Answer all questions. Importantly, answer yes to
          autodoc: automatically insert docstrings from modules (y/N) [n]:
          
        4. This should produce a directory structure like so:
          • Makefile
          • _build
          • _static
          • _templates
          • conf.py
          • index.rst
        5. Now we can run
          $ make html

          to create the first version of our docs. This will create the _build/html directory containing the html files

        6. Open index.html in the browser and you should see your empty (for the moment) project docs
        7. Now, to make use of the handy autodoc extension, we need to make sure conf.py is setup properly. First check that the autodoc extension is enabled:
          # Add any Sphinx extension module names here, as strings. They can be extensions
          # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
          extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.pngmath', 'sphinx.ext.viewcode']

          Then edit the file to include the path and Django project settings:

          # documentation root, use os.path.abspath to make it absolute, like shown here
          sys.path.insert(0, os.path.abspath('.'))
          # setup Django
          import settings
          from django.core.management import setup_environ
          setup_environ(settings)
        8. Now we can test this by referencing our first module. Create another directory called /modules in the project root and created models.rst to reference my models.py module in my app. In this write:
          Models
          =======
          
          .. automodule:: myapp.models
              :members:
          
          
        9. Now in index.rst we can add a reference to this module:
          Contents:
          =========
          
          .. toctree::
          :maxdepth: 2
          
          modules/models.rst
          
          Indices and tables
          ==================
          
          * :ref:`genindex`
          * :ref:`modindex`
          * :ref:`search`
        10. The autodoc extension should automatically extract information and comments about the models from models.
        11. Run
          $ make html

          again and refresh the docs in the browser. Now there should be section entitled models and page listing the classes, fields and comments of your models.py module

        12. From here you can explore some of the further options in autodoc such as:
          Models:
          ======
          
          .. automodule:: myapp.models
              :members:
              :undoc-members:
              :inherited-members:

Some useful links:

Advertisements

2 thoughts on “Setting up Sphinx Documentation with Django

  1. Pingback: Django, Sphinx docs and Buildout | Restless Being

  2. Worked perfect for me… đŸ™‚ Thanks a lot !! Was struggling with it since day or two with documentation. Followed your steps and it worked just fine for me. Hope it does for other’s as well.. Good work Keep Going …

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s