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
Add information about autogenerated methods
Fix intersphinx mappings to Django modules
Custom text roles to cross-reference the documentations of Django (
:fieldlookup:) and Sphinx (
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 = [ "sphinxcontrib_django", ] # 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
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.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
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.