Google style Python docstrings#

At IDM, we use Google style formatted Python docstrings. For more information, see the following resources, listed in order of relevance:

Google style docstring examples
PEP 257 docstring conventions.
PEP 484 annotation (Sphinx will build API documentation with the type for each parameter listed if type hints are included in the function/method definition.)
Google style guide on docstrings (Note that we do not follow Google’s guidance to use descriptive instead of imperative verbs, choosing to follow the PEP 257 guidance instead.)
Python 3 documentation

See Text editors: Write the source for information on how to configure common text editors to automatically create stubbed out docstrings in the Google format. See Configure the build for information on configuring a docset to include autogenerated API reference content.

Code snippets#

The parameter list in Python docstrings is formatted very similar to a definition list. Remember to introduce code snippets with a double colon, indent the code sample, and include a blank line before and after the code. For example:

Introductory paragraph describing the function.

Args:
    parameter1: This is a short definition.
    parameter2: This is a longer definition. I need to include so much
        information that it needs a second line. Notice the indentation.
    parameter3: This is a definition that needs a code example to
        make the information more clear. Do that like so::

            def function_name():
                print('Tada!')

    parameter4: This is the parameter following the sample code. Notice
        the indentation and preceding blank line.

Example sections#

It’s usually a good practice to include a usage example in the docstring, particularly for more complicated functions/methods. The style guidance for Google style docstrings shows the following format, with a plain paragraph immediately after the section heading:

Example:

Introductory paragraph. Sections support any reStructuredText
formatting, including literal blocks::

    import idmtools
    function(3, "my string")

However, if you attempt to follow the “Example” section heading directly with a code sample, this will not display “Example” as a section heading in the compiled HTML. If you do not want to include an introductory paragraph, use the following format to include a section heading immediately followed by a code sample:

**Example**::

    import idmtools
    function(3, "my string")

Referencing Python objects#

To refer to other Python objects, such as methods or classes, in the docstring you can create a link using the following syntax:

:py:class:`idmtools.entities.itask.ITask
:py:func:`add_drug_campaign`
:py:class:`~emod_api.demographics.Demographics.Demographics`

You must include the full dot notation with the module and class if referencing an object outside the current module; the preceding dot notation is optional if you are referencing an object in the same module. To exclude the dot notation from the name in the output HTML, prepend the reference with a tilde (~). For more information, see cross-referencing syntax.

If you are referencing a Python object in another library docset that is included in the intersphinx mapping defined in conf.py, you can use the same Python object cross-reference syntax. You do not need to include the name of the docset being referenced as you do with :doc: links. For example, see the following valid links to emod_api, the first is a :doc: link to an RST topic and the second is a link to the API reference generated from docstings:

:doc:`emod_api:index`
:py:class:`emod_api.demographics.Demographics.Demographics`

For more information on intersphinx, see Linking to other docsets.

Test the doc build#

It’s important to test the documentation build locally before submitting docstring changes. See Sphinx: Build the HTML output and Sphinx build troubleshooting.

Autogenerated API reference requires Sphinx to import all package dependencies for the code being documented, such as functions that are inherited from numpy or other third-party packages. Problems with the requirements.txt or setup.py file not specifying all required packages or specifying an incompatible version are the most common doc build problems encountered.

If you are the project owner for a software tool that includes API reference in the documentation, we encourage you to get a Read the Docs account so you can view the build logs to troubleshoot issues of this type. Contact Helpdesk for an account.