GitHub Workflow Status PyPi Code coverage Black Code Style GitHub license Documentation Status



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


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:)


Install the package via pip:

pip install sphinxcontrib-django


Add the following to your Sphinx config file

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

# Add sphinxcontrib_django to installed extensions
extensions = [

# 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                # Boolean, default: False
# Add abstract database tables names (only takes effect if django_show_db_tables is True)
django_show_db_tables_abstract = True       # Boolean, default: False

Optionally, you can extend amount of displayed choices in model fields with them:

# Integer amount of model field choices to show, default 10
django_choices_to_show = 10

Advanced Usage

If you want to run custom code which depends on Django, e.g. to monkeypatch your application during documentation build, you might run into an ImproperlyConfigured exception:

Requested setting INSTALLED_APPS, but settings are not configured. You must either define the environment variable DJANGO_SETTINGS_MODULE or call settings.configure() before accessing settings.

Therefore, this Sphinx extension emits the event django-configured after django.setup() is finished, so you can run your code the following way in

def patch_django(app):
    Your custom code here

def setup(app):
    app.connect("django-configured", patch_django)


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.