Numpydoc docstrings#

When writing docstrings for PyAnsys libraries, follow the syntax and best practices described in Style guide in the numpydoc Manual.

For consistency within PyAnsys libraries, always use """ to introduce and conclude a docstring, keeping the line length shorter than 70 characters. Ensure that there are no blank spaces at the end of a line because they cause errors in build checks that you must then resolve.

A blank line signifies the start of a new paragraph. To create a bulleted or numbered list, ensure that there is a blank line before the first item and after the last item. Because you use the same markup in docstrings as you do in RST files, see Quick reStructuredText for a markup summary.

Surround any text that you want to set apart as literal text (code entities) in double backticks to render it in a monospaced font within a gray box. Use double backticks to surround the names of files, folders, classes, methods, and variables.

For example:

"""Initialize the ``Desktop`` class with the version of AEDT to use."""

Note

While the numpydoc style guide says to surround the names of classes, methods, and variables in a single backtick, you must use double backticks. Surrounding text in a single backtick in a PyAnsys library formats it in italic type rather than as a code entity.

Required docstring sections#

PyAnsys library docstrings contain these numpydoc sections as a minimum:

These sections should follow numpydoc style. To avoid inconsistencies between PyAnsys libraries, see Docstring formatting rules.

Examples#

The “Examples” section provides one or more small code samples that make usage of a method or function clear. They provide an easy place to start when trying out the API.

Here is a sample “Examples” section from a Python file for PyAEDT.

Examples
--------
Create an instance of HFSS and connect to an existing HFSS
design or create a new HFSS design if one does not exist.

>>> from pyaedt import Hfss
>>> hfss = Hfss()
pyaedt info: No project is defined...
pyaedt info: Active design is set to...

Code supplied in an “Examples” section must be compliant with the doctest format. This allows the code to be used through pytest to perform regression testing to verify that the code is executing as expected.

If the definition of a method or function is updated, the code in the “Examples” section must be updated. Any change within the API without a corresponding change in the example code triggers a doctest failure.

Examples are not meant to replace a test suite but rather complement it. Because examples must always match the API that they are documenting, they are an important feature of maintainable documentation.

Type hints#

By default, Sphinx renders type hints as part of the function signature per PEP 484 – Type Hints. This can become difficult to read because the signature becomes very long.

Instead, you should render type hints as part of each parameter’s description. To accomplish this, you must combine the sphinx.ext.autodoc.typehints, sphinx.ext.napoleon, and numpydoc extensions in the conf.py file in this order:

extensions = [
    ...,
    "sphinx.ext.autodoc.typehints",
    "sphinx.ext.napoleon",
    "numpydoc",
    ...,
]
autodoc_typehints = "description"

When using type hints in this way, you can omit the type information in the “Parameters” and “Returns” sections.

Additional directives#

Because Python docstrings are written using reStructuredText syntax, you can take advantage of some of the directives available in this plaintext markup language. Here are some Sphinx directives that can be used in docstrings, although they should be used sparingly as they do not look very good in text terminals.

  • note: Highlights important information to be aware of.

  • warning: Points out an action that might result in data loss or cause some other issue, such as performance degradation.

  • deprecated: X.Y.Z Indicates the deprecation status of an object or feature.

Example#

Here is a generic docstring example compliant with PyAnsys guidelines:

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

    Extended description of the function. The extended description,
    which can span multiple lines, should provide a general overview
    of the function.

    .. warning::
       Use the ``warning`` directive within the docstring for any
       warnings that need to be explicitly stated. For example, you
       want to include a warning for a method that is to be deprecated
       in the next release.

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

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

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

    """
    return True

To include the docstring of a function within Sphinx, you use the autofunction directive:

.. autofunction:: ansys_sphinx_theme.examples.sample_func.func

This directive renders the sample function as:

ansys_sphinx_theme.examples.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:

  • arg1 (int) – Description of arg1.

  • arg2 (str) – Description of arg2.

Returns:

Description of return value.

Return type:

bool

Examples

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