Generating API documentation from docstrings

This page shows how the docstring example in our example docstring sample page can be rendered in the project web pages using the sphinx autodoc extension.

The docstring content of a module is converted to HTML by including a small Markdown file in the docs/source/api folder. The source of this page provides an example and can be seen following the ‘Edit on GitHub’ link at the top of the page to GitHub and then clicking on the ‘Raw’ button to see the text.

You also need to include a link to that new file in the table of contents for the website. To do this you need to put a link in the API section of the sphinx index file found at docs/source/index.md.

The docstring Markdown file has three components:

The file will start with the jupytext YAML metadata, which just sets the Markdown format used in the file.
A markdown header (# A header), which is shown as the page title. It is also used as the text for links to this page from the table of contents, unless a shorter name is provided in the index.md file. Typically, this header is the only markdown content in the file as the point of the docstrings is to keep all actual module documentation within the module code file.
Lastly, an automodule instruction is included to instruct autodoc to render and insert content of the module docstrings.

The basic automodule declaration and options used are:

.. automodule:: docstring_style
    :autosummary:
    :members:
    :special-members: __repr__

The autosummary option adds summary tables of the module objects below the module docstring content and above the docstrings for those objects. The members option includes all public module members in the documentation. These settings can be extended from a range of options if required. Here, for example, the special-members option is used to make sure the __repr__ method and its docstrings are included. This option covers all ‘dunder’ methods (__special__) of classes. Similarly, the private-members allows private functions and methods (_func or __func) to be included in the API documentation if needed.

Note that we should not include :special-members: __init__ in the automodule options: creating a class instance is documented by the class docstring.

Rendered content

All of the content below this box is rendered from the example docstring code.

This is the documentation for the module. It does not start with a header line because a header is required at the top of the markdown source page where the API docs will be inserted using the automodule declaration, so we do not repeat it here.

That does mean that we need to stop flake8 complaining about a missing blank line after the first line and a missing full stop at the end of that line, which we can do using the comment # noqa: D205, D415 after the docstring closes.

Data:

AN_OBJECT

This is a docstring for a module attribute.

Classes:

MyClass(myarg, name)

This is my class.

Functions:

multiplier(arg1, arg2)

Multiply two integers.

docstring_style.AN_OBJECT: str = 'An object in the module': This is a docstring for a module attribute.

class docstring_style.MyClass(myarg: int, name: str)

This is my class.

This is some text about my class

Parameters:: myarg – An argument used to create an instance of MyClass. Arguments are documented here in the class docstring and not in an __init__ docstring.

Methods:

`__repr__`()	Create a text representation of the class.
`multiply_me`(factor)	Multiples myarg by a factor.

Attributes:

`a_class_attribute`	A Class attribute.
`myarg`	The myarg value used to create the instance.
`myarg_multiple`	An instance attribute.
`name`	The instance name.

__repr__() → str: Create a text representation of the class.

a_class_attribute: int = 0

A Class attribute.

Attributes are documented with docstrings underneath the attribute definition. Class attributes are grouped with instance attributes in the rendered documentation, so should say explictly that they are a class attribute.

multiply_me(factor: int) → int

Multiples myarg by a factor.

Methods must define any arguments and provide Returns and Raises sections if appropriate.

Parameters:: factor – An integer factor by which to multiply self.myarg.
Returns:: The value of self.myarg multiplied by the provided factor. This result is also stored in self.myarg_multiple.
Raises:: ValueError – if the provided factor is not an integer.

myarg: int

The myarg value used to create the instance.

All attributes of a class instance should be defined and typed in the __init__ method, even if they are not used or populated in the __init__ method. This ensures that they are picked up and included in the rendered docstrings.

myarg_multiple: int

An instance attribute.

This attribute is not populated in __init__ but must be defined and documented here.

name: str: The instance name.

docstring_style.multiplier(arg1: int, arg2: int) → int

Multiply two integers.

This function calculates the product of two integers. The docstring documents the arguments, return value and any exceptions that can be raised.

Parameters:

arg1 – The first integer
arg2 – The second integer

Returns:

The product of the two integers.

Raises:

ValueError – if either argument is not an integer.