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, what, name, obj, skip, options)
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.
- sphinxcontrib_django.docstrings.improve_docstring(app, what, name, obj, options, lines)
Hook to improve the autodoc docstrings for Django models (see
autodoc-process-docstring
).- Parameters:
what (str) – The type of the object which the docstring belongs to (one of
module
,class
,exception
,function
,method
andattribute
)name (str) – The fully qualified name of the object
obj (object) – The documented object
options (object) – 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 (list [ str ]) – 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
- Return type:
- sphinxcontrib_django.docstrings.setup(app)
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 (Sphinx) – The Sphinx application object
- sphinxcontrib_django.docstrings.setup_django(app, config)
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:
- 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, include_role=True)
Get the type of a field including the correct intersphinx mappings.
- sphinxcontrib_django.docstrings.field_utils.get_field_verbose_name(field)
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 (Field) – The field
Attributes
This module contains all functions which are used to improve the documentation of attributes.
- sphinxcontrib_django.docstrings.attributes.get_field_details(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(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_model_parameters(fields, lines, field_docs)
Add the given fields as model parameter with the
:param:
directive
- sphinxcontrib_django.docstrings.classes.improve_class_docstring(app, cls, lines)
Improve the documentation of a class if it’s a Django model or form
- sphinxcontrib_django.docstrings.classes.improve_form_docstring(form, lines)
Improve the documentation of a Django
Form
class. This highlights the available fields in the form.
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
- 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)