# sphinxcontrib_django

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

sphinxcontrib_django.setup(app: Sphinx) → dict

  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 – 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: Sphinx, config: Config) → None

  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 – The Sphinx application object

    - config – The Sphinx configuration

sphinxcontrib_django.roles.setup(app: Sphinx) → dict

  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 – The Sphinx application object