Skip to content

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

License

Notifications You must be signed in to change notification settings

CloverHealth/sphinxcontrib-django

 
 

Repository files navigation

https://img.shields.io/travis/edoburu/sphinxcontrib-django/master.svg?branch=master

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
]

About

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

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Python 100.0%