Documentation example

Using the sphinx_autodoc_variants extension, primary and variant functions can be grouped together as a single function group.

Functions

With the sphinx_autodoc_variants extension enabled in conf.py, function groups at the module level will automatically be grouped together by the automodule directive. To explicitly document a function group, use the autoprimary_function directive:

.. autoprimary_function:: examples.example_variants.primary_func
    :members:

Which generates:

examples.example_variants.primary_func(x, y)

This is the primary function. Its docstring should be shown under the primary function documentation.

primary_func.onearg(x)

This is the onearg variant, it only takes one argument.

primary_func.threearg(x, y, z)

This is the threearg variant, it takes three arguments.

Methods

For a class containing function group methods, the autoclass directive works, so:

.. autoclass:: examples.example_variants.VariantMethodsClass
    :members:

Resulting in:

class examples.example_variants.VariantMethodsClass

normal_method(a, b)

This is a normal method, it has no variants

primary_method(x, y)

This is the primary method, its docstring should be shown under the primary method documentation.

primary_method.onearg(x)

This is the onearg variant, it takes one argument.

As with functions, individual method groups can be documented using the autoprimary_method directive:

.. autoprimary_method:: examples.example_variants.VariantMethodsClass.primary_method
    :members:

Which generates:

VariantMethodsClass.primary_method(x, y)

This is the primary method, its docstring should be shown under the primary method documentation.

primary_method.onearg(x)

This is the onearg variant, it takes one argument.