ADR Suggestion Docstring Style Standardization

[AndrewSazonov]

This ADR proposes standardizing docstrings across all repositories in the EasyScience GitHub organization using the NumPy-style.

The decision is based on a comparison of the three main docstring styles currently relevant to our tooling and documentation workflow: Sphinx-style, Google-style, and NumPy-style. All three styles are supported by our documentation build tools (MkDocs + mkdocstrings) and produce equivalent user-facing API reference documentation. Therefore, the main differences is in developer experience and tooling support.

NumPy-style is the suggested choice for the following reasons:

• Sphinx-style is less readable in source code than both Google-style and NumPy-style, as it relies on inline :param: and :rtype: fields, which add visual noise.
• Google-style is more readable, but tooling and formatter support is weaker. In practice, tools struggle to correctly parse and reformat sections such as "Args" and "Returns". In addition, the commonly used tool docformatter has dependency limitations that currently block Python 3.14 support.
• NumPy-style remains readable in code while offering strong tooling and formatter support. The tool format-docstring provides nice automatic formatting for NumPy-style docstrings. In addition, the tool pydoclint, which we use for docstring linting and which supports all three styles, provides more advanced checks for NumPy-style docstrings, namely, ensuring that type hints in the docstring are consistent with default values in the function signature.

For these reasons, NumPy-style provides the best balance between readability in source code, maintainability, and tooling support, while preserving the same rendered API documentation quality in our documentation pipeline.

Examples

From the insert method in the CollectionBase class (easyscience package).

Sphinx-style:

"""
Insert an object into the collection at an index.

:param index: Index for EasyScience object to be inserted.
:type index: int
:param value: Object to be inserted.
:type value: Union[BasedBase, DescriptorBase, NewBase]
:return: None
:rtype: None
"""

Google-style:

"""
Insert an object into the collection at an index.

Args:
    index (int): Index for EasyScience object to be inserted.
    value (Union[BasedBase, DescriptorBase, NewBase]): Object to be
        inserted.

Returns:
    None
"""

NumPy-style:

"""
Insert an object into the collection at an index.

Parameters
----------
index : int
    Index for EasyScience object to be inserted.
value : Union[BasedBase, DescriptorBase, NewBase]
    Object to be inserted.

Returns
-------
None
"""

[rozyczko]

I understand the reasoning for NumPy formatting but for me it seems too verbose.
It is very line hungry. Every parameter gets a section-header underline, and the type goes on a separate line from the description.
For short functions with one or two simple parameters, we can end up with a docstring 3–4x longer than the function body.
Google-style has the same information within fewer lines
Also, there is redundancy with type hints. If the signatures already have type annotations the NumPy-style docstr duplicates them

def insert(self, index: int, value: BasedBase) -> None:
    """
    Parameters
    ----------
    index : int        # redundant
        The index.
    value : BasedBase   # redundant
        The object.
    """

Obviously the tooling will help with maintaining correspondence between args and docstrings but the maintenance cost of all those tools is constantly growing.

[damskii9992]

I really dislike the sphinx-style . . .
I slightly prefer the NumPy style over the Google style, but the additional available tooling with the Numpy style feels like a stronger selling point to choose that style over the Google style.

Also, there is redundancy with type hints. If the signatures already have type annotations the NumPy-style docstr duplicates them

This looks redundant at first glance, but in practice it’s impossible to avoid.

Documentation tools that generate API reference pages rely on docstrings, not function signatures, for type information.

What we can do (and already do in the templates) is enforce consistency - e.g. checking that types and default values in docstrings match the function signature. This way, if the signature changes, the linting step will fail until the docstring is updated.

It feels like the documentation tools should get updated to automatically use the function signatures typing to avoid this extra check/redundancy . . .
Oh well, one can hope that this changes some day, until then we will have to live with it :)
I am in favor of this ADR.

[henrikjacobsenfys]

I agree we should all use the same style, and it seems there are good reasons to choose NumPy. I'm a bit sad that I'll have to reformat all my docstrings from Google style, but perhaps there are tools to help with it.

[AndrewSazonov]

We can try this https://pypi.org/project/docstripy/

[rozyczko]

We can try this https://pypi.org/project/docstripy/

lol they need to check their own docs

[AndrewSazonov]

Yeah, would be nice to have a tool that formats docs and also catches/fixes typos like this. Maybe something like that already exists (besides Copilot etc.)?