mauler / sphinxcontrib-django

Improvements for the output of Sphinx's autodoc for Django classes.

sphinxcontrib-django

Improvements for the output of Sphinx's autodoc for Django classes.

This adds the following improvements:

• Properly show which fields a model has.
• Properly show which fields a form has.
• Document the model fields as parameters in the model __init__().
• Link foreign key and related fields to the documentation of the referenced class.
• Hide irrelevant runtime information like declared_fieldsets, fieldsets and Meta from classes.
• A :django:setting: role to allow linking to Django documentation. (e.g. :django:setting:`SITE_ID`)

Installation

Usage:

pip install sphinxcontrib-django

Add to the Sphinx config file (:file:`conf.py`):

extensions = [
    'sphinx.ext.autodoc',
    'sphinxcontrib_django',
]

Autodoc works by importing your code on the fly, and extracting the data from the Python classes. Thus, the project should be able to import Django models. Typically the following needs to be added to :file:`conf.py`:

sys.path.insert(0, os.path.abspath('../src'))
os.environ['DJANGO_SETTINGS_MODULE'] = 'myapp.settings'
django.setup()

To support the :django:setting: role, configure Intersphinx:

intersphinx_mapping = {
    'http://docs.python.org/': None,
    'https://docs.djangoproject.com/en/stable': 'https://docs.djangoproject.com/en/stable/_objects',
}

Recommendations:

When your project uses Celery, include celery.contrib.sphinx too. This adds an autotask:: directive, and ``:task:`app.tasks.my_task```*role.

Other great extensions are:

• sphinx-autodoc-annotation: Converts Python 3 annotations to docstrings.
• sphinx.ext.graphviz: Allows to create diagrams with ease.

An example configuration may look like:

extensions = [
    'sphinx.ext.autodoc',         # The autodoc core
    'sphinx.ext.graphviz',        # Support creating charts!

    'celery.contrib.sphinx',      # Celery improvements!
    'sphinx_autodoc_annotation',  # Parses Python 3 annotations
    'sphinxcontrib_django',       # this module
]