sphinxcontrib-django2 0.7

Improve the Sphinx autodoc for Django classes.

sphinxcontrib-django2

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

This is a fork of sphinxcontrib-django, which seems to be no longer maintained. In comparison to the upstream repository, this provides the following:

• Support for current versions of Python and Django

• Support for ModelForms

• Support Intersphinx mappings to Django classes

• 100% test coverage

The original repository already implemented the following features:

• 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-django2

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

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

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',
}

Contributing

Pull requests are always welcome!

You can install all requirements of the development setup with Pipenv:

pipenv install --dev
pipenv run pre-commit install

Then, run the tests with:

pipenv run coverage run runtests.py