A domain is a collection of markup, consisting of directives and roles, that describe and link to objects belonging together, such as elements of a programming language.
See also
The following sections show examples of the built-in domains of Sphinx.
Using Sphinx’s sphinx.ext.autodoc plugin,
it is possible to auto-generate documentation of a Python module.
Tip
Avoid having in-function-signature type annotations with autodoc, by setting the following options:
# -- Options for autodoc ----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration
# Automatically extract typehints when specified and place them in
# descriptions of the relevant function/method.
autodoc_typehints = "description"
# Don't show class signature with the class' name.
autodoc_class_signature = "separated"
automodule Directive with reStructuredText Markup¶The following markup is an example of the automodule directive.
Note that the currentmodule directive sets the current module.
.. currentmodule:: all_in_one_restructuredtext
.. automodule:: all_in_one_restructuredtext
:members:
:member-order: bysource
The foregoing markup example renders as shown below.
This is the module-level docstring of the module all_in_one_restructuredtext.
The module’s docstrings use reStructuredText markup.
Docstring of type ParameterT
alias of TypeVar(‘ParameterT’)
The docstring of my_module_level_variable.
This function accepts any number of arguments and keyword arguments.
Note
If you do not use sphinx.ext.napoleon:
In the source code,
the docstring for this function is a “raw” docstring using r"""...""",
and *args and **kwargs below are escaped with a backslash
(\*args and \*\*kwargs).
*args – Variable length argument list.
**kwargs – Arbitrary keyword arguments.
None
Text at end of docstring.
This function accepts any number of arguments and keyword arguments.
Note
If you do not use sphinx.ext.napoleon:
In the source code,
the docstring for this function is a “raw” docstring using r"""...""",
and *args and **kwargs below are escaped with a backslash
(\*args and \*\*kwargs).
*args – Variable length argument list.
**kwargs – Arbitrary keyword arguments.
None
Text at end of docstring.
This function accepts any number of arguments and keyword arguments.
Note
If you use sphinx.ext.napoleon (and only then),
there is no need to escape *args and **kwargs below.
*args – Variable length argument list.
**kwargs – Arbitrary keyword arguments.
None
Text at end of docstring.
A simple function.
foo – A regular argument.
bar – Another regular argument.
None
Deprecated since version x.y: (This is an example of a deprecation admonition.)
Use my_function_pure_sphinx() instead.
Text at end of docstring.
This is a class that demonstrates various Python features.
It uses Google-style docstrings (https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html).
A private property of the class.
A normal method.
We are using both positional-only and keyword-only syntax.
Here is some code in a literal block:
foo = True # assign ``True``
Note
Do not include the self parameter in the Args section.
my_param – Documenting my_param. This is another sentence on the next docstring line, still belonging to my_param.
keyword_only_param – Documenting keyword_only_param. This is another sentence on the next docstring line, still belonging to keyword_only_param.
The value of the local variable my_var.
MyException – if something went wrong.
Example
>>> retval = my_method() # doctest format
"return_value"
Text at end of docstring.
An async method.
Text at end of docstring.
A classmethod.
Text at end of docstring.
A staticmethod.
Text at end of docstring.
Getter for the private property _my_property.
The value of _my_property.
Text at end of docstring.