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.