Docstring Style#

Purpose#

The project uses NumPy-style docstrings (Parameters, Returns, Attributes, Raises, Examples, See Also, etc.) throughout the codebase. This is checked automatically on every pull request by Codacy using pydocstyle, and issues show up there as minor “Documentation” findings (e.g. D401: First line should be in imperative mood). Fixing these locally before pushing saves a round trip through CI.

Checking your code locally#

Install pydocstyle, if you don’t already have it:

pip install pydocstyle

Then run it against the package, using the numpy convention (this matches the docstring style already used in this codebase):

pydocstyle --convention=numpy src/sigmaepsilon/math

To check a single file or a single directory instead of the whole package:

pydocstyle --convention=numpy src/sigmaepsilon/math/optimize/bga.py
pydocstyle --convention=numpy src/sigmaepsilon/math/linalg

No output and a zero exit code means the checked files are clean. Each finding is reported as a file, line number, and a pydocstyle error code (D1xx for missing docstrings, D2xx for whitespace/formatting, D4xx for content rules) with a short explanation, for example:

src/sigmaepsilon/math/optimize/state.py:11 in public class `OptimizerState`:
        D401: First line should be in imperative mood (perhaps 'Return', not 'Returns')

Most common findings and how to fix them#

D100-D107 (missing docstring) — every public module, class, method, function, and magic method needs a docstring. Add a concise, accurate one-liner describing what the code actually does.
D200 (one-liner should fit on one line) — a docstring with a single sentence and no additional sections should be written as """Do X.""", not spread across multiple lines.
D205 (blank line required between summary and description) — if a docstring has a longer description or a Parameters/Returns/etc. section below the summary sentence, leave one blank line between the summary and everything that follows.
D400/D401 (first line: period, imperative mood) — the summary line must end with a period and use the imperative mood, e.g. """Return the dual frame.""" rather than """Returns the dual frame.""".
D405 (section name capitalization) — NumPy-style section headers must be capitalized exactly as Parameters, Returns, Attributes, Raises, Examples, See Also, etc.
D301 (use a raw string for docstrings containing backslashes) — docstrings with LaTeX-style math (e.g. \mathbf, \left) must be written as raw strings, r"""...""", to avoid SyntaxWarning: invalid escape sequence and to have the backslashes render correctly.

Things to keep in mind while fixing docstrings#

These are docstring-only fixes: never change code behavior while fixing a docstring finding.
Preserve the existing NumPy-style section structure and content — only fix the flagged formatting/wording issue, don’t rewrite documentation that’s already accurate.
Doctest-style examples (lines starting with >>>) are executed as tests by tests/test_docstrings.py. Reformatting a docstring must not change the behavior or output of any >>> example it contains.
Run Black on any file you touch, since docstring edits can shift line wrapping:

poetry run black src/

Note

pydocstyle’s built-in conventions have a couple of pairs of mutually exclusive checks (for example D203/D211 and D212/D213) that cannot both be satisfied at once. The numpy convention used here already resolves these in the codebase’s favor, so running with --convention=numpy locally should match what Codacy reports. If Codacy ever flags one side of such a pair that isn’t covered by the numpy convention, that’s a Codacy tool configuration issue rather than something to fix in the code — raise it with whoever administers the project’s Codacy settings.