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:

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)