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).

See also https://github.com/sphinx-doc/sphinx/issues/9893.

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).

See also https://github.com/sphinx-doc/sphinx/issues/9893.

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.

all_in_one_restructuredtext.my_generator()[source]#

A generator.

Yields:

None

exception all_in_one_restructuredtext.MyException[source]#

Custom exception class.

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.

abstractmethod my_abstractmethod() → ReturnT[source]#

An abstract 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.

my_decorator_method()[source]#

A decorator method that wraps the provided method.

Parameters:

method – The method to decorate.

Returns:

The decorated method.

Text at end of docstring.

my_decorated_method()[source]#

The decorated method.

final class all_in_one_restructuredtext.MyFinalClass[source]#

A class that cannot be subclassed.

final my_final_method() → None[source]#

A method that cannot be overridden by subclasses.

all_in_one_restructuredtext.my_decorator_function(function)[source]#

A decorator function that wraps the provided function.

Parameters:

function – The function to decorate.

Returns:

The decorated function.

Text at end of docstring.

all_in_one_restructuredtext.my_decorated_function()[source]#

The decorated function.