Skip to content

Fix and improve docstring documentation#601

Open
llucax wants to merge 10 commits into
frequenz-floss:v0.x.xfrom
llucax:fix-docstrings
Open

Fix and improve docstring documentation#601
llucax wants to merge 10 commits into
frequenz-floss:v0.x.xfrom
llucax:fix-docstrings

Conversation

@llucax

@llucax llucax commented Jul 1, 2026

Copy link
Copy Markdown
Contributor

🤖 This pull request is part of an automated effort to improve the docstring documentation of all our projects.

Main issues being resolved:

  • Typos in docstrings (including a wrong `tools.pytest` config section name and `mkdocs-literary-nav` plugin name)
  • Grammatical mistakes, missing words and unclear wording
  • Boolean accessor summaries using "Tell whether ..." / "Check if ..." instead of "Return whether ..."
  • Class and attribute summaries not using the conventional noun-phrase mood ("A ..." / "The ...")
  • Missing `Args:` and `Raises:` sections (and a placeholder "Post init." summary)
  • Bare backtick symbol mentions that should be cross-reference links
  • Absolute cross-references replaced with relative ones where applicable
  • Macro variable names that used link syntax but are not Python symbols
  • Broken code examples (unbalanced parentheses, missing import)

Other things to note:

  • `relative_crossrefs: true` was added to the mkdocstrings options in `mkdocs.yml` as part of the rolling-out of relative cross-reference conventions.
  • `check-style-mismatch` and `require-inline-class-var-docs` were added to the pydoclint config in `pyproject.toml`, and `check-class-attributes` was re-enabled (it had been disabled because the project documents attributes inline; `require-inline-class-var-docs` now enforces exactly that inline style, so the check is useful again). The source tree already complies with these checks.
  • The `nox/default.py` module docstring described the default config variables with a "respectively" mapping that listed the repository types in the wrong order and omitted models; this was corrected.
  • A copy-pasted summary in `generate_protobuf_api_pages()` that described Python modules instead of protocol buffer files was fixed.
  • These changes only touch the `frequenz.repo.config` package's own docstrings and configuration. The equivalent `cookiecutter/` template files (and a corresponding `migrate.py` step) were intentionally left out of scope and may need a separate change to propagate the `relative_crossrefs` / pydoclint convention to generated repositories.

llucax added 5 commits July 1, 2026 15:00
@llucax
Enable relative cross-references in mkdocstrings
c19f530 
Add `relative_crossrefs: true` to the mkdocstrings Python handler
options to support relative cross-references in docstrings.

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
@llucax
Align pydoclint config with rolled-out conventions
a096cf7 
Add `check-style-mismatch = true` and `require-inline-class-var-docs =
true`, and re-enable `check-class-attributes = true`.

`check-class-attributes` was previously disabled (in pydoclint 0.5.3)
because the project documents class attributes with inline docstrings
rather than an `Attributes:` section.  The new
`require-inline-class-var-docs` option enforces exactly that inline
style, so the check is now useful again instead of conflicting with the
project's conventions.

The source tree already complies, so no docstrings need to change for
these checks to pass.

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
@llucax
Fix typos in docstrings
ef96e68 
Correct several misspellings and an incorrect config section name
(`tools.pytest` -> `tool.pytest`, `mkdocs-literary-nav` ->
`mkdocs-literate-nav`) found across the source docstrings.

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
@llucax
Fix grammar and wording in docstrings
2d1ad27 
Fix several grammatical mistakes, missing words, unbalanced backticks
and parentheses, and a copy-pasted summary in
`generate_protobuf_api_pages()` that incorrectly described Python
modules instead of protobuf files.

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
@llucax
Use imperative mood for boolean accessor summaries
53728bf 
Boolean-returning functions should start their summary with "Return
whether ..." per the docstring conventions, instead of "Tell whether"
or "Check if".

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
@llucax llucax requested a review from a team as a code owner July 1, 2026 13:00
@llucax llucax requested review from shsms and removed request for a team July 1, 2026 13:00
@github-actions github-actions Bot added part:docs Affects the documentation part:tooling Affects the development tooling (CI, deployment, dependency management, etc.) part:nox Affects the configuration of nox part:protobuf Affects the protobuf tools part:mkdocs Affects the configuration of mkdocs part:pytest Affects the configuration of pytest labels Jul 1, 2026
@llucax llucax added this to the v0.19.0 milestone Jul 1, 2026
llucax added 5 commits July 1, 2026 15:25
@llucax
Cross-reference symbols mentioned in docstrings
56900bd 
Turn bare backticked mentions of public symbols (classes, functions and
module-level variables) into proper cross-references so they render as
links.  Also de-link a few macro variable names (`version`,
`version_requirement`, `code_annotation_marker`) that used link
syntax but are not Python symbols, to avoid mis-resolved references.

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
@llucax
Use relative cross-references in docstrings
468ec60 
Convert absolute cross-references to relative ones where the target is
the same module, a sibling, or a member of the current package,
following the `relative_crossrefs` convention being rolled out.  This
also shortens the rendered link text in the user guide (e.g. `nox`
instead of `frequenz.repo.config.nox`).

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
@llucax
Improve class and attribute summary docstrings
c41193f 
Use the conventional summary mood: a noun phrase starting with "A" for
classes and "The" for attributes.  Also fix an inaccurate `__init__`
summary (it does not initialize environment variables) and add a missing
inline docstring for a public class attribute.

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
@llucax
Fix broken examples in docstrings
9a50019 
Add a missing closing parenthesis in the `flatten()` example and an
explicit `import pathlib` to the `existing_paths()` example so the
snippets are syntactically valid and self-contained.

Also replace some `Example:` admonitions with an `Examples:` section,
otherwise they are not shown as code.

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
@llucax
Update release notes
5a6c600 
Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
@llucax llucax enabled auto-merge July 1, 2026 13:26
@llucax llucax requested a review from Marenz July 10, 2026 15:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@shsms shsms Awaiting requested review from shsms shsms is a code owner automatically assigned from frequenz-floss/python-sdk-team
@Marenz Marenz Awaiting requested review from Marenz

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

part:docs Affects the documentation part:mkdocs Affects the configuration of mkdocs part:nox Affects the configuration of nox part:protobuf Affects the protobuf tools part:pytest Affects the configuration of pytest part:tooling Affects the development tooling (CI, deployment, dependency management, etc.)

Projects

None yet

Milestone

v0.19.0

Development

Successfully merging this pull request may close these issues.

1 participant

@llucax