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,
.. 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'
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'
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
.. 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
@propertydecorator should be documented in the property’s getter method.
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.
Do not include the
selfparameter in the
>>> example.example_method('foo', 'bar') True
- property readonly_property: str¶
Properties should be documented in their getter method.
>>> 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.
>>> example.readwrite_property "readwrite_property"
>>> example.readwrite_property = 'hello world' >>> example.readwrite_property 'hello world'
Simple classes can be easily represented using the
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:
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.