Documentation Style

PyAnsys packages should pick either the Google or Numpy documentation style when writing their docstrings. Adhering to this style permits the usage of the sphinx.ext.napoleon extension, which is included in sphinx in version 1.3 and later.

Methods and functions should generally be documented with the Examples docstring section to make the usage of the method or function clear. Here is a sample function:

def func(arg1, arg2):
    """Summary line <should be one one line>.

    Extended description of function.  Can span multiple lines and
    provides a general overview of the function.

    .. warning::
       Use the ``.. warning::`` directive within the doc-string for any
       warnings you would like to explicitly state.  For example, if
       this method will be deprecated in the next release.

    Parameters
    ----------
    arg1 : int
        Description of arg1.
    arg2 : str
        Description of arg2.

    Returns
    -------
    bool
        Description of return value.

    Examples
    --------
    >>> func(1, 'foo')
    True

    """
    return True

To include the docstring of function within sphinx, use the autofunction:: directive:

.. autofunction:: pyansys_sphinx_theme.sample_func.func

Which causes the function to be rendered as:

pyansys_sphinx_theme.sample_func.func(arg1, arg2)

Summary line <should be one one line>.

Extended description of function. Can span multiple lines and provides a general overview of the function.

Warning

Use the .. warning:: directive within the doc-string for any warnings you would like to explicitly state. For example, if this method will be deprecated in the next release.

Parameters
arg1int

Description of arg1.

arg2str

Description of arg2.

Returns
bool

Description of return value.

Examples

>>> func(1, 'foo')
True

More Details

Additional examples and notes regarding Numpy or Google docstrings can be found at sphinx.ext.napoleon. Attempt to follow a consistent documentation style whenever possible.