Skip to content

docs: convert remaining RST docstring constructs to Google style #1172

@planetf1

Description

@planetf1

During the audit for PR #1155 (backtick normalisation), 12 files were found containing ~83 RST-style docstring constructs that could not be converted by mechanical substitution. They require editorial restructuring into the project's Google-style docstring convention.

Affected files

File RST constructs present
mellea/formatters/granite/base/io.py :param, :type, :returns:, :rtype:
mellea/formatters/granite/granite3/granite32/input.py :param, :type
mellea/formatters/granite/granite3/granite33/input.py :param, :type
mellea/formatters/granite/granite3/input.py :param, :type
mellea/formatters/granite/intrinsics/input.py :param, :type, :returns:
mellea/formatters/granite/intrinsics/output.py :param, :type
mellea/formatters/granite/retrievers/embeddings.py :param, :type
mellea/stdlib/components/genslot.py :param, :returns:
mellea/stdlib/components/intrinsic/_util.py :param, :type
mellea/stdlib/components/intrinsic/core.py :param, :type, .. note::
mellea/stdlib/components/intrinsic/guardian.py :param, :returns:
mellea/core/utils.py .. deprecated::, .. note::

Also noted

mellea/stdlib/requirements/python_reqs.py line 75–76 has a comment/regex inconsistency: the comment says # Pattern for generic \`` blocks(triple backtick / Markdown) but the regex matches``` (RST double backtick). The comment should be corrected to match the regex, or the regex extended to handle both styles.

Open style decision

Several docstrings use triple-backtick fenced code blocks (e.g. model_options.py, session.py, genstub.py) while others use RST :: notation. Before addressing the files above, the project should agree on the preferred style for code examples in docstrings — triple-backtick fences are more readable and Markdown-native, but inconsistent with remaining RST usage. This decision should be recorded in CONTRIBUTING.md so it does not resurface on future PRs.

Out of scope

Mechanical backtick substitution (the work done in #1155). This issue covers only constructs that require understanding the surrounding context to restructure correctly.

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentation

Type

No type
No fields configured for issues without a type.

Projects

No projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions