sphinxcontrib-django

2.5 · active · verified Thu Apr 16

sphinxcontrib-django is a Sphinx extension that significantly improves the documentation of Django applications. It enhances Sphinx's autodoc by automatically listing model and form fields as parameters, improving field representations, linking related fields, and hiding irrelevant runtime details. Additionally, it provides custom text roles for cross-referencing Django's settings, template tags, filters, and admin commands. The library is currently at version 2.5 and actively maintained.

Common errors

```
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.
```
cause Sphinx autodoc is trying to import Django models or forms before the Django settings have been loaded and the Django application registry initialized.

fix In your `conf.py`, ensure you have set `os.environ['DJANGO_SETTINGS_MODULE'] = 'your_project.settings'` and called `django.setup()` after adjusting `sys.path` to include your Django project.
```
ModuleNotFoundError: No module named 'your_django_app'
```
cause Sphinx cannot find your Django application modules because the Python path (`sys.path`) does not include your project's root directory or the directory containing your apps.

fix In your `conf.py`, add the path to your Django project's root (or where your apps reside) to `sys.path`. For example: `sys.path.insert(0, os.path.abspath('../src'))` if your Django project is in `src` relative to `docs`.
```
Sphinx generates empty documentation for Django models/forms.
```
cause The `sphinxcontrib-django` extension is either not correctly enabled, Django's environment is not initialized, or autodoc directives (`automodule`, `autoclass`, etc.) are missing or misconfigured in your `.rst` files.

fix Verify that `'sphinxcontrib_django'` is in your `extensions` list in `conf.py`, ensure `django.setup()` is called, and check your `.rst` files for correct `autodoc` directives (e.g., `.. automodule:: myapp.models` and `.. autoclass:: myapp.models.MyModel`). Ensure `django_settings` is also correctly set in `conf.py`.

Warnings

breaking When using Sphinx 9.x or later, the `autodoc_use_legacy_class_based = True` setting might be required in `conf.py` to ensure proper autodoc functionality with Django classes. Failure to do so can result in incomplete or incorrect documentation.
Fix: Add `autodoc_use_legacy_class_based = True` to your `conf.py` file.
gotcha Failure to correctly configure Django settings can lead to `ImproperlyConfigured` exceptions during the Sphinx build process, preventing documentation generation. This typically happens when Django's environment is not properly set up before autodoc attempts to import models or forms.
Fix: Ensure `os.environ['DJANGO_SETTINGS_MODULE']` is set to your project's settings file and `django.setup()` is called in your `conf.py` before any Django-dependent imports. Also, add your Django project's root to `sys.path`.
deprecated Previous versions of `sphinxcontrib-django` (and underlying Django/Python versions) have dropped support for older Python and Django releases. Ensure your environment matches the library's requirements to avoid compatibility issues.
Fix: Check the `CHANGES.rst` or release notes for your specific `sphinxcontrib-django` version to confirm compatibility with your Python and Django versions. Upgrade `sphinxcontrib-django`, Python, or Django as necessary.

Install

pip install sphinxcontrib-django Install with pip

Imports

sphinxcontrib_django
```
extensions = ['sphinx.ext.autodoc', 'sphinxcontrib_django']
```
This library is a Sphinx extension, not typically imported directly in Python code. It is added to the `extensions` list in `conf.py`.

Quickstart

To quickly set up `sphinxcontrib-django`, first install it via pip. Then, create your Sphinx documentation project using `sphinx-quickstart`. Edit your `conf.py` file to include `sphinxcontrib_django` in the `extensions` list, configure the path to your Django project, set the `DJANGO_SETTINGS_MODULE` environment variable, and call `django.setup()`. This ensures Sphinx can properly load and inspect your Django models and forms. Remember to adjust `sys.path.insert` and `django_settings` to match your project structure. For Sphinx versions 9 and above, you might need to enable `autodoc_use_legacy_class_based`.

import os
import sys
import django

# Adjust this path to your Django project's root directory
sys.path.insert(0, os.path.abspath('../src'))

# Configure Django settings module
os.environ['DJANGO_SETTINGS_MODULE'] = 'myproject.settings'

# Initialize Django
django.setup()

# -- Project information -----------------------------------------------------
project = 'My Django Project'
copyright = '2026, Your Name'
author = 'Your Name'
release = '0.1'

# -- General configuration ---------------------------------------------------
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.intersphinx',
    'sphinxcontrib_django',
]

intersphinx_mapping = {
    'django': ('https://docs.djangoproject.com/en/stable/', 'https://docs.djangoproject.com/en/stable/_objects'),
    'python': ('http://docs.python.org/', None),
}

# sphinxcontrib-django specific configuration
django_settings = 'myproject.settings'

# Required for Sphinx >= 9 with autodoc
# autodoc_use_legacy_class_based = True

# Optional: show database table names
django_show_db_tables = True

view raw JSON →