Skip to main content

Improve the Sphinx autodoc for Django classes.

Project description

https://img.shields.io/travis/edoburu/sphinxcontrib-django/master.svg?branch=master https://img.shields.io/pypi/v/sphinxcontrib-django.svg https://img.shields.io/pypi/l/sphinxcontrib-django.svg https://img.shields.io/codecov/c/github/edoburu/sphinxcontrib-django/master.svg

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 (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 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
]

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinxcontrib-django-0.3.tar.gz (11.7 kB view hashes)

Uploaded Source

Built Distribution

sphinxcontrib_django-0.3-py2.py3-none-any.whl (11.7 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page