API documentation#

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"

This is a demo module included in the docs in order to exercise autodoc.

class lutra._demo_module.RandomNumberGenerator#

A random number generator.

__init__(*, seed=4)#

Initialize.

Parameters:: seed (int) –
Return type:: None

get_random_float()#

Return a random float.

Return type:: float

get_random_integer()#

Return a random integer.

Return type:: int

property seed: int#: Get seed for random number generation.

See also

https://xkcd.com/221/

lutra._demo_module.show_warning(message, category, filename, lineno, file=None, line=None)#

Show a warning to the end user.

warnings.showwarning = show_warning

Parameters:

message (Warning | str) – What you want to tell the user.
category (Type[Warning]) – The type of warning.
filename (str) – The file that the warning is for.
lineno (int) – The line that the warning is for.
file (TextIO | None) – Where to write the warning.
line (str | None) – line of source code to be included in the warning message

Return type:

None