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
ormodule
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
andattribute
)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
andnoindex
that areTrue
if the flag option of same name was given to the auto directivelines – 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
andautodoc-process-docstring
.Additionally, the sphinx config value
django_settings
is added viaadd_config_value()
andsetup_django()
is called on theconfig-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’sconf.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.
- 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.
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
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:
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 isdjango.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)