# Docstrings

Improve the docstrings of Django apps.

For example:

- List all model and form fields as parameters (see:mod:~sphinxcontrib_django.docstrings.classes)

- Improve field representations in the documentation (see `attributes`)

- Add information about autogenerated methods (see `methods`)

- Improve the appearance of static iterable data (see `data`)

- Fix the intersphinx mappings to the Django documentation (see `patches`)

sphinxcontrib_django.docstrings.autodoc_skip(app: Sphinx, what: str, name: str, obj: object, options: Options, lines: list[str]) → bool | None

  Hook to tell autodoc to include or exclude certain fields (see `autodoc-skip-member`).

  Sadly, it doesn’t give a reference to the parent object, so only the `name` can be used for referencing.

  Parameters:

    - app – The Sphinx application object

    - what – The parent type, `class` or `module`

    - name – The name of the child method/attribute.

    - obj – The child value (e.g. a method, dict, or module reference)

    - options – The current autodoc settings.

sphinxcontrib_django.docstrings.improve_docstring(app: Sphinx, what: str, name: str, obj: object, options: Options, lines: list[str]) → list[str]

  Hook to improve the autodoc docstrings for Django models (see `autodoc-process-docstring`).

  Parameters:

    - what – The type of the object which the docstring belongs to (one of `module`, `class`, `exception`, `function`, `method` and `attribute`)

    - name – The fully qualified name of the object

    - obj – The documented object

    - options – The options given to the directive: an object with attributes `inherited_members`, `undoc_members`, `show_inheritance` and `noindex` that are `True` if the flag option of same name was given to the auto directive

    - lines – A list of strings – the lines of the processed docstring – that the event handler can modify in place to change what Sphinx puts into the output.

  Returns:

    The modified list of lines

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

  Allow this package to be used as Sphinx extension.

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

  It connects to the sphinx events `autodoc-skip-member` and `autodoc-process-docstring`.

  Additionally, the sphinx config value `django_settings` is added via `add_config_value()` and `setup_django()` is called on the `config-inited` event.

  Parameters:

    app – The Sphinx application object

sphinxcontrib_django.docstrings.setup_django(app: Sphinx, config: Config) → None

  This function calls `django.setup()` so it doesn’t have to be done in the app’s `conf.py`.

  Called on the `config-inited` event.

  Parameters:

    - app – The Sphinx application object

    - config – The Sphinx configuration

  Raises:

    ConfigError – If setting `django_settings` is not set correctly

## Field Utilities

This module contains utility functions for fields which are used by both the `attributes` and `classes` modules.

sphinxcontrib_django.docstrings.field_utils.get_field_type(field: Field, include_role: bool = True) → str

  Get the type of a field including the correct intersphinx mappings.

  Parameters:

    - field – The field

    - include_directive – Whether or not the role `py:class` should be included

  Returns:

    The type of the field

sphinxcontrib_django.docstrings.field_utils.get_field_verbose_name(field: Field) → str

  Get the verbose name of the field. If the field has a `help_text`, it is also included.

  In case the field is a related field, the `related_name` is used to link to the remote model. For reverse related fields, the originating field is linked.

  Parameters:

    field – The field

sphinxcontrib_django.docstrings.field_utils.get_model_from_string(field: Field, model_string: str) → type[Model]

  Get a model class from a string

  Parameters:

    - field – The field

    - model_string – The string label of the model

  Returns:

    The class of the model

## Attributes

This module contains all functions which are used to improve the documentation of attributes.

sphinxcontrib_django.docstrings.attributes.get_field_details(app, field)

  This function returns the detail docstring of a model field. It includes the field type and the verbose name of the field.

  Parameters:

    - app (Sphinx) – The Sphinx application object

    - field (Field) – The field

  Returns:

    The field details as list of strings

  Return type:

    list [ str ]

sphinxcontrib_django.docstrings.attributes.improve_attribute_docstring(app, attribute, name, lines)

  Improve the documentation of various model fields.

  This improves the navigation between related objects.

  Parameters:

    - app (Sphinx) – The Sphinx application object

    - attribute (object) – The instance of the object to document

    - name (str) – The full dotted path to the object

    - lines (list [ str ]) – The docstring lines

## Classes

This module contains all functions which are used to improve the documentation of classes.

sphinxcontrib_django.docstrings.classes.add_db_table_name(app: Sphinx, model: Model, lines: list[str]) → None

  Format and add table name by extension configuration.

  Parameters:

    - app – The Sphinx application object

    - model – The instance of the model to document

    - lines – The docstring lines

sphinxcontrib_django.docstrings.classes.add_model_parameters(fields: list[Field], lines: list[str], field_docs: dict) → None

  Add the given fields as model parameter with the `:param:` directive

  Parameters:

    - fields – The list of fields

    - lines – The list of current docstring lines

    - field_docs – The attribute docstrings of the model

sphinxcontrib_django.docstrings.classes.improve_class_docstring(app: Sphinx, cls: type, lines: list[str]) → None

  Improve the documentation of a class if it’s a Django model or form

  Parameters:

    - app – The Sphinx application object

    - cls – The instance of the class to document

    - lines – The docstring lines

sphinxcontrib_django.docstrings.classes.improve_form_docstring(form: Form, lines: list[str]) → None

  Improve the documentation of a Django `Form` class. This highlights the available fields in the form.

  Parameters:

    - form – The form object

    - lines – The list of existing docstring lines

sphinxcontrib_django.docstrings.classes.improve_model_docstring(app: Sphinx, model: Model, lines: list[str]) → None

  Improve the documentation of a Django `Model` subclass.

  This adds all model fields as parameters to the `__init__()` method.

  Parameters:

    - app – The Sphinx application object

    - model – The instance of the model to document

    - lines – The docstring lines

## Data

sphinxcontrib_django.docstrings.data.improve_data_docstring(data, lines)

  Improve the documentation of data by pretty-printing into in the docstring.

  Parameters:

    - data (object) – The documented object

    - lines (list [ str ]) – The lines of docstring lines

## Methods

This module contains all functions which are used to improve the documentation of methods.

sphinxcontrib_django.docstrings.methods.improve_method_docstring(name, lines)

  Improve the documentation of methods automatically contributed to models by Django:

  - `get_FOO_display()`

  - `get_next_by_FOO()`

  - `get_previous_by_FOO()`

  Parameters:

    - name (str) – The full dotted path to the object.

    - lines (list [ str ]) – The lines of docstring lines

## Patches

This module contains patches for Django to improve its interaction with Sphinx.

sphinxcontrib_django.docstrings.patches.patch_django_for_autodoc()

  Fix the appearance of some classes in autodoc. E.g. the absolute path to the base model class is `django.db.models.base.Model`, but its intersphinx mapping path is `django.db.models.Model`.

  This also avoids query evaluation.

## Config

This module contains configuration of the members which should in-/excluded in sphinx (see `autodoc-skip-member`)

sphinxcontrib_django.docstrings.config.CHOICES_LIMIT = 10

  How many choices should be shown for model fields by default, used as default for `django_choices_to_show` option

sphinxcontrib_django.docstrings.config.EXCLUDE_MEMBERS = {'Meta', 'base_fields', 'content_panels', 'declared_fields', 'declared_fieldsets', 'fieldsets', 'panels', 'polymorphic_primary_key_name', 'polymorphic_super_sub_accessors_replaced'}

  Members to hide.

sphinxcontrib_django.docstrings.config.INCLUDE_MEMBERS = {'__init__'}

  Ensure that the __init__ method gets documented (also see `autoclass_content` setting)