API Documentation

User Guide Documentation Method

There are two main ways of documenting a class using Sphinx. The first approach is to detail its usage via a “User Guide”, or manually created example designed to be read within documentation. This approach works when demonstrating the usage of a class. For example, using the .. code:: python directive:

Initialize ``my_module.MyClass`` with initial parameters.  These
parameters are automatically assigned to the class.

 .. code:: python

    >>> from my_module import MyClass
    >>> my_obj = MyClass(parm1='apple', parm2='orange')
    >>> my_obj.parm1
    'apple'

Initialize my_module.MyClass with initial parameters. These parameters are automatically assigned to the class.

>>> from my_module import MyClass
>>> my_obj = MyClass(parm1='apple', parm2='orange')
>>> my_obj.parm1
'apple'

Autoclass Directive

The “User Guide” approach works for explaining the “why” and “how” of a class. As for the “what” of a class, you can describe the API automatically using the autoclass directive:

.. autoclass:: pyansys_sphinx_theme.samples.ExampleClass
    :members:
class pyansys_sphinx_theme.samples.ExampleClass(param1, param2, param3=0)

The summary line for a class docstring should fit on one line.

Attributes should be documented inline with the attribute’s declaration.

Properties created with the @property decorator should be documented in the property’s getter method.

Parameters
param1str

Description of param1.

param2list of str

Description of param2. Multiple lines are supported.

param3int, optional

Description of param3.

Examples

An example of how to initialize this class should be given.

>>> from pyansys_sphinx_theme import samples
>>> example = samples.ExampleClass('mystr', ['apple', 'orange'], 3)
example_method(param1, param2)

Class methods are similar to regular functions.

Parameters
param1str

The first parameter.

param2str

The second parameter.

Returns
bool

True if successful, False otherwise.

Notes

Do not include the self parameter in the Parameters section.

Examples

>>> example.example_method('foo', 'bar')
True
property readonly_property: str

Properties should be documented in their getter method.

Examples

>>> example.readonly_property
"readonly_property"
property readwrite_property

Set or return the readwrite property.

Properties with both a getter and setter should only be documented in their getter method.

If the setter method contains notable behavior, it should be mentioned here.

Examples

>>> example.readwrite_property
"readwrite_property"
>>> example.readwrite_property = 'hello world'
>>> example.readwrite_property
'hello world'

Autosummary Directive

Simple classes can be easily represented using the autoclass directive. However, more complex classes with many methods should be documented via the autosummary directive. For example:

.. autosummary::
   :toctree: _autosummary

   pyansys_sphinx_theme.samples.Complex

This code will generate the following documentation:

pyansys_sphinx_theme.samples.Complex(real[, ...])

Custom implementation of a complex number.

Each class will have its own dedicated page, and each method and attribute in that class will also have its own page.