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 furo._demo_module.RandomNumberGenerator(*, seed: int = 4)

A random number generator.

get_random_float() → float

Return a random float.

get_random_integer() → int

Return a random integer.

property seed: int

Get seed for random number generation.

See also

https://xkcd.com/221/

furo._demo_module.annoying_function_name_length_aa(one: int, two: int) → str

Add two numbers as strings.

Because I needed a placeholder function.

furo._demo_module.annoying_function_name_length_aaa(one: int, two: int) → str

Add two numbers as strings.

Because I needed a placeholder function.

furo._demo_module.show_warning(message: Warning | str, category: Type[Warning], filename: str, lineno: int, file: TextIO | None = None, line: str | None = None) → None

Show a warning to the end user.

warnings.showwarning = show_warning

Parameters:

• message – What you want to tell the user.

• category – The type of warning.

• filename – The file that the warning is for.

• lineno – The line that the warning is for.

• file – Where to write the warning.

• line – line of source code to be included in the warning message

C inline signature

type my_type

This works my_type, but I would like to point to a pointer of the type (my_type*).