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.
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
mellea/formatters/granite/base/io.py:param,:type,:returns:,:rtype:mellea/formatters/granite/granite3/granite32/input.py:param,:typemellea/formatters/granite/granite3/granite33/input.py:param,:typemellea/formatters/granite/granite3/input.py:param,:typemellea/formatters/granite/intrinsics/input.py:param,:type,:returns:mellea/formatters/granite/intrinsics/output.py:param,:typemellea/formatters/granite/retrievers/embeddings.py:param,:typemellea/stdlib/components/genslot.py:param,:returns:mellea/stdlib/components/intrinsic/_util.py:param,:typemellea/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.pyline 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.