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"
# To avoid generating type ints for undocuments parameters and return values
autodoc_typehints_description_target = "documented"

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

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

class furo._demo_module.RandomNumberGenerator(*, seed=4)

A random number generator.

Parameters:

seed (int)

property seed: int

Get seed for random number generation.

Added in version 1.0.

Changed in version 1.1: Use random to create the seed.

Deprecated since version 1.2: random raises security concerns.

Removed in version 1.3: random replaced with a random number.

See also

https://xkcd.com/221/

get_random_integer()

Return a random integer.

Return type:

int

get_random_float()

Return a random float.

Return type:

float

furo._demo_module.annoying_function_name_length_aa(one, two)

Add two numbers as strings.

Because I needed a placeholder function.

Parameters:
Return type:

str

furo._demo_module.annoying_function_name_length_aaa(one, two)

Add two numbers as strings.

Because I needed a placeholder function.

Parameters:
Return type:

str

C inline signature

type my_type

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