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)[source] 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
[source] -
normal_method
(a, b)[source] This is a normal method, it has no variants
-
primary_method
(x, y)[source] 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: