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)[source]#

A random number generator.

get_random_float() → float[source]#

Return a random float.

get_random_integer() → int[source]#

Return a random integer.

property seed: int#

Get seed for random number generation.

See also

https://xkcd.com/221/

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

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