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.application.Sphinx, what: str, name: str, obj: object, options: sphinx.ext.autodoc.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.application.Sphinx, what: str, name: str, obj: object, options: sphinx.ext.autodoc.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.application.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.application.Sphinx, config: 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: django.db.models.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: django.db.models.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: django.db.models.Field, model_string: str) → type[django.db.models.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.application.Sphinx, model: django.db.models.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[django.db.models.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.application.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: django.forms.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.application.Sphinx, model: django.db.models.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)