audit-docstrings

Python docstring guidelines

Skill version: 1.1_2026.07.21

Use Google-style docstrings. Every public class, method, and function should have a docstring that helps a disease-modeling researcher understand not just what the object does, but where it fits in their workflow. Use American English spelling and usage.

If using Material for MkDocs to build documentation, the plugin mkdocstrings renders docstrings as API reference content. Local modules are documented automatically; to include external packages, use the mkdocs-gen-files plugin and associated Python script.

If using Quarto to build documentation, list all modules in the quarto.yml config file for them to be documented. Configure the docstring parser format as follows:

quartodoc:
  parser: google

Structure of a good docstring

def some_function(arg1, arg2):
    """ One-line summary ending with a period.

    Two to four sentences of prose explaining what this does and why a researcher
    would reach for it. Mention the disease model context — is this used during
    initialization, timestep updates, or post-simulation analysis?

    Link to related objects using MkDocs cross-reference syntax, e.g.
    [`Model`][laser.generic.model.Model] or [`Susceptible`][laser.generic.components.Susceptible].

    Args:
        arg1 (array): Description including shape, dtype, and units where
            relevant. E.g. "Shape ``(nticks+1, num_nodes)``, dtype float32."
        arg2 (int): Description. State default values explicitly if they matter.

    Returns:
        array: What is returned, its shape, dtype, and interpretation.
            For None returns, omit this section entirely.

    Raises:
        ValueError: When and why this is raised.

    Examples:

        # Show the most common researcher workflow. Use a self-contained snippet
        # that a researcher can run or adapt directly:

        model = Model(scenario, params)
        result = some_function(model.nodes.S[0], model.params.nticks)

    Note:
        Reserve for non-obvious caveats — performance warnings, thread safety,
        or behaviors that diverge from what the name implies.
    """