sphinxcontrib-django2 1.2

Improve the Sphinx autodoc for Django classes.

sphinxcontrib-django2

This is a sphinx extension which improves the documentation of Django apps.

Features

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

• List all model and form fields as class parameters

• Improve model field representations

• Link related and reverse related fields to the referenced class

• Hide irrelevant runtime information like declared_fieldsets, fieldsets and Meta from classes

• Add information about autogenerated methods

• Fix intersphinx mappings to Django modules

• Custom text roles to cross-reference the documentations of Django (:setting:, :templatetag:, :templatefilter:, :fieldlookup:) and Sphinx (:event:, :confval:)

This is a fork of sphinxcontrib-django, which seems to be no longer maintained.

Installation

Install the package via pip:

pip install sphinxcontrib-django2

Configuration

Add the following to your Sphinx config file conf.py:

# Add source directory to sys.path
sys.path.insert(0, os.path.abspath("../src"))

# Add sphinxcontrib_django2 to installed extensions
extensions = [
    "sphinxcontrib_django2",
]

# Configure the path to the Django settings module
django_settings = "myapp.settings"

Optionally, you can include the table names of your models in their docstrings with:

# Include the database table names of Django models
django_show_db_tables = True

Contributing

Pull requests are always welcome!

You can install all requirements of the development setup with the extras dev, test, doc and optional:

python3 -m venv .venv
source .venv/bin/activate
pip install -e .[dev,test,doc,optional]
pre-commit install

Run the tests and generate the coverage report with:

coverage run
coverage html

Build the documentation with:

cd docs
make html

The documentation is automatically deployed to Read the Docs.