API documentation#
Using autodoc#
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"
The automodule
Directive with reStructuredText Markup#
What follows is an example showing usage of the .. automodule::
directive.
This is the module-level docstring of the module all_in_one_restructuredtext
.
The module’s docstrings use reStructuredText markup.
- class all_in_one_restructuredtext.ParameterT#
Docstring of type ParameterT
alias of TypeVar(‘ParameterT’)
- class all_in_one_restructuredtext.ReturnT#
Docstring of type ReturnT.
alias of TypeVar(‘ReturnT’)
- all_in_one_restructuredtext.MyType#
The docstring.
alias of
list
[float
]
- all_in_one_restructuredtext.my_module_level_variable: list[float] = [0.0, 1.1]#
The docstring.
- all_in_one_restructuredtext.my_function_pure_sphinx(*args, **kwargs)[source]#
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
).- Parameters:
*args – Variable length argument list.
**kwargs – Arbitrary keyword arguments.
- Returns:
None
Text at end of docstring.
- all_in_one_restructuredtext.my_function_google_style(*args, **kwargs)[source]#
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
).- Parameters:
*args – Variable length argument list.
**kwargs – Arbitrary keyword arguments.
- Returns:
None
Text at end of docstring.
- all_in_one_restructuredtext.my_function_needs_napoleon(*args, **kwargs)[source]#
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.- Parameters:
*args – Variable length argument list.
**kwargs – Arbitrary keyword arguments.
- Returns:
None
Text at end of docstring.
- all_in_one_restructuredtext.my_function2(foo: int, bar: str)[source]#
A simple function.
- Parameters:
foo – A regular argument.
bar – Another regular argument.
- Returns:
None
Deprecated since version 2.0: Use
my_function_pure_sphinx()
instead.Text at end of docstring.
- class all_in_one_restructuredtext.AllInOne[source]#
This is a class that demonstrates various Python features.
Uses Google-style docstrings (https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html).
- _my_property#
A private property of the class.
- my_method(my_param: ParameterT = 'default_value', /, *, keyword_only_param=None) ReturnT [source]#
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.- Parameters:
my_param – Documenting my_param. Another sentence on the next docstring line, still belonging to my_param.
keyword_only_param – Documenting keyword_only_param. Another sentence on the next docstring line, still belonging to keyword_only_param.
- Returns:
The value of the local variable
my_var
.- Raises:
MyException – if something went wrong.
Example
>>> retval = my_method() # doctest format "return_value"
Text at end of docstring.
- async my_async_method(my_param: ParameterT = 'default_value') ReturnT [source]#
An async method.
Text at end of docstring.
- classmethod my_classmethod(my_param: ParameterT = 'default_value') ReturnT [source]#
A
classmethod
.Text at end of docstring.
- static my_staticmethod(my_param: ParameterT = 'default_value') ReturnT [source]#
A
staticmethod
.Text at end of docstring.
- property my_property#
Getter for the private property
_my_property
.- Returns:
The value of
_my_property
.
Text at end of docstring.