sphinxcontrib_django

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

sphinxcontrib_django.setup(app)

Allow this module to be used as sphinx extension.

Setup the two sub-extensions docstrings and roles which can also be imported separately.

Parameters:

app (Sphinx) – The Sphinx application object

Docstrings

• Docstrings
  • autodoc_skip()
  • improve_docstring()
  • setup()
  • setup_django()
  • Field Utilities
    • get_field_type()
    • get_field_verbose_name()
    • get_model_from_string()
  • Attributes
    • get_field_details()
    • improve_attribute_docstring()
  • Classes
    • add_db_table_name()
    • add_model_parameters()
    • improve_class_docstring()
    • improve_form_docstring()
    • improve_model_docstring()
  • Data
    • improve_data_docstring()
  • Methods
    • improve_method_docstring()
  • Patches
    • patch_django_for_autodoc()
  • Config
    • CHOICES_LIMIT
    • EXCLUDE_MEMBERS
    • INCLUDE_MEMBERS

Roles

This module adds cross-reference types which are used in the documentation of Django and Sphinx to allow intersphinx mappings to these custom types. The supported text roles are:

Django:

• :setting:, e.g. :setting:`INSTALLED_APPS` renders as INSTALLED_APPS

• :templatetag:, e.g. :templatetag:`block` renders as block

• :templatefilter:, e.g. :templatefilter:`add` renders as add

• :fieldlookup:, e.g. :fieldlookup:`equals` renders as equals

Sphinx:

• :event:, e.g. :event:`autodoc-skip-member` renders as autodoc-skip-member

• :confval:, e.g. :confval:`extensions` renders as extensions

This module can also be used separately in conf.py:

extensions = [
    "sphinxcontrib_django.roles",
]

sphinxcontrib_django.roles.add_default_intersphinx_mappings(app, config)

This function provides a default intersphinx mapping to the documentations of Python, Django and Sphinx if intersphinx_mapping is not given in conf.py.

Called on the config-inited event.

Parameters:

• app (Sphinx) – The Sphinx application object

• config (Config) – The Sphinx configuration

sphinxcontrib_django.roles.setup(app)

Allow this module to be used as Sphinx extension.

This is also called from the top-level setup().

It adds cross-reference types via add_crossref_type().

Parameters:

app (Sphinx) – The Sphinx application object