Documenting code with type hints

Many DM packages (especially the middleware suite) use type hints for static analysis, which often duplicates the type information included in docstrings. Documentation built with Documenteer 2.x can often leave this information out, because the sphinx-autodoc-typehints extension (included automatically) will parse the annotations and include type information in the docs automatically.

Note

pipelines.lsst.io is currently still built with Documenteer 1.x, but is expected to transition soon. While some package doc builds have already been upgraded in anticipation of this transition, their documentation content needs to remain compatible with Documenteer 1.x for now.

Function arguments

To document the parameters to a function or method declared with type hints, use regular numpydoc style without the colon or the type information that follows it:

def run_thing(self, x: int, *args: int, name: str = "", **kwargs: str) -> None:
    """Run the thing.

    Parameters
    ----------
    x
        X coordinate.
    *args
        Some other coordinates.
    name
        The name of the thing.
    **kwargs
        Names of other things.
    """

Note that , optional is also unnecessary, as are defaults; default values are automatically pulled from the real function signature.

Function return values

Return types work automatically when they are not documented at all:

def return_it() -> str:
    """Return the thing."""
    return ""

This is a reasonable approach when there is nothing else to document about the returned object. When the returned object does merit additional documentation, the type does unfortunately need to be written out (duplicating the annotation), but the returned object should not be named:

def return_it() -> str:
    """Return the thing.

    Returns
    -------
    str
        The thing.
    """
    return ""

A simple return type does not need backticks to create a link, but backticks may be needed for more complex types (e.g. generics):

from collections.abc import Sequence

def return_stuff() -> Sequence[str]:
    """Return some stuff.

    Returns
    -------
    `~collections.abc.Sequence` [`str`]
        The stuff.
    """
    return []

Note

As always, types in docstrings do not respect imports in the file, and instead are resolved using the Sphinx target-resolution rules. See Links to Python objects for details.

Functions that return multiple values via a tuple should have their return types documented just like parameters, i.e. with labels and no types:

def return_pair() -> tuple[str, int]:
    """Return a pair.

    Returns
    -------
    name
        The name.
    id
        The ID.
    """
    return ("", 0)

Properties and attributes

Annotations on properties and attributes are not applied to documentation automatically. Their docstrings should continue to include the types parenthetically:

class Thing:
    """A thing."""

    @property
    def name(self) -> str:
        """Name of the thing (`str`)."""
        return ""

    value: int = 0
    """Value of the thing (`int`)."""

Note

Attributes without default values (or some sort of = RHS) are not included in documentation at all, except for those on dataclass types. Important instance attributes that cannot have a class-level default value should be made into properties so they can be documented.