API documentation

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

Domains

The following sections show examples of the built-in domains of Sphinx.

• Directives in the C domain
• Directives in the C++ domain
• Directives in the JavaScript domain
• Directives in the Python domain
• Directives in the reStructuredText domain

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

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.

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 of MyType using an explicit TypeAlias.

alias of list[float]

all_in_one_restructuredtext.my_module_level_variable: list[float] = [0.0, 1.1]

The docstring of my_module_level_variable.

all_in_one_restructuredtext.my_function_pure_sphinx(*args, **kwargs)

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)

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)

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)

A simple function.

Parameters:

• foo – A regular argument.

• bar – Another regular argument.

Returns:

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.

all_in_one_restructuredtext.my_generator()

A generator.

Yields:

None

exception all_in_one_restructuredtext.MyException

Custom exception class.

class all_in_one_restructuredtext.AllInOne

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

_my_property

A private property of the class.

my_method(my_param: ParameterT = 'default_value', /, *, keyword_only_param=None) → ReturnT

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

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

An async method.

Text at end of docstring.

abstractmethod my_abstractmethod() → ReturnT

An abstract method.

Text at end of docstring.

classmethod my_classmethod(my_param: ParameterT = 'default_value') → ReturnT

A classmethod.

Text at end of docstring.

static my_staticmethod(my_param: ParameterT = 'default_value') → ReturnT

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

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

The decorated method.

final class all_in_one_restructuredtext.MyFinalClass

A class that cannot be subclassed.

final my_final_method() → None

A method that cannot be overridden by subclasses.

all_in_one_restructuredtext.my_decorator_function(function)

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

The decorated function.