{"id":8675,"library":"sphinxcontrib-django","title":"sphinxcontrib-django","description":"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.","status":"active","version":"2.5","language":"en","source_language":"en","source_url":"https://github.com/sphinx-doc/sphinxcontrib-django","tags":["sphinx","django","documentation","autodoc","extension"],"install":[{"cmd":"pip install sphinxcontrib-django","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Core documentation generation engine, required by the extension.","package":"Sphinx","optional":false},{"reason":"The framework whose applications are being documented.","package":"Django","optional":false}],"imports":[{"note":"This library is a Sphinx extension, not typically imported directly in Python code. It is added to the `extensions` list in `conf.py`.","symbol":"sphinxcontrib_django","correct":"extensions = ['sphinx.ext.autodoc', 'sphinxcontrib_django']"}],"quickstart":{"code":"import os\nimport sys\nimport django\n\n# Adjust this path to your Django project's root directory\nsys.path.insert(0, os.path.abspath('../src'))\n\n# Configure Django settings module\nos.environ['DJANGO_SETTINGS_MODULE'] = 'myproject.settings'\n\n# Initialize Django\ndjango.setup()\n\n# -- Project information -----------------------------------------------------\nproject = 'My Django Project'\ncopyright = '2026, Your Name'\nauthor = 'Your Name'\nrelease = '0.1'\n\n# -- General configuration ---------------------------------------------------\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx.ext.intersphinx',\n    'sphinxcontrib_django',\n]\n\nintersphinx_mapping = {\n    'django': ('https://docs.djangoproject.com/en/stable/', 'https://docs.djangoproject.com/en/stable/_objects'),\n    'python': ('http://docs.python.org/', None),\n}\n\n# sphinxcontrib-django specific configuration\ndjango_settings = 'myproject.settings'\n\n# Required for Sphinx >= 9 with autodoc\n# autodoc_use_legacy_class_based = True\n\n# Optional: show database table names\ndjango_show_db_tables = True\n","lang":"python","description":"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`."},"warnings":[{"fix":"Add `autodoc_use_legacy_class_based = True` to your `conf.py` file.","message":"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.","severity":"breaking","affected_versions":"Sphinx >= 9.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"deprecated","affected_versions":"< 2.0 (e.g., versions prior to 2.2 dropped Python 2.7/3.5 and Django < 2.2 support)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"Sphinx autodoc is trying to import Django models or forms before the Django settings have been loaded and the Django application registry initialized.","error":"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."},{"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`.","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.","error":"ModuleNotFoundError: No module named 'your_django_app'"},{"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`.","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.","error":"Sphinx generates empty documentation for Django models/forms."}]}