Skip to main content

Improve the Sphinx autodoc for Django classes.

Project description

GitHub Workflow Status PyPi Code coverage Black Code Style GitHub license

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

Project details


Download files

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

Source Distribution

sphinxcontrib-django2-0.7.tar.gz (15.9 kB view hashes)

Uploaded Source

Built Distribution

sphinxcontrib_django2-0.7-py2.py3-none-any.whl (16.5 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