Skip to content

docs(api): normalize source docstring backticks#659

Open
Kemalau wants to merge 1 commit intogenerative-computing:mainfrom
Kemalau:clawoss/docs-rst-backticks-657
Open

docs(api): normalize source docstring backticks#659
Kemalau wants to merge 1 commit intogenerative-computing:mainfrom
Kemalau:clawoss/docs-rst-backticks-657

Conversation

@Kemalau
Copy link

@Kemalau Kemalau commented Mar 16, 2026

Why

The docstring source still contains RST-style double backticks across the Python package and CLI, so the docs pipeline has to normalize them at generation time. Cleaning up the source keeps the docstrings consistent with the project's Markdown/Google-style convention and addresses issue #657 directly.

What changed

  • replaced RST-style symbol notation with Markdown-style symbol notation in Python string literals under mellea/ and cli/
  • kept fenced code blocks intact so literal triple-backtick examples still render correctly
  • verified the edited Python sources still compile after the bulk replacement

Verification

  • python -m compileall mellea cli
  • scanned mellea/ and cli/ for remaining inline double-backtick occurrences after the replacement (only triple-backtick fence literals remain)

Fixes #657

@Kemalau Kemalau requested review from a team, jakelorocco and nrfulton as code owners March 16, 2026 18:05
@mergify
Copy link

mergify bot commented Mar 16, 2026

Merge Protections

Your pull request matches the following merge protections and will not be merged until they are valid.

🟢 Enforce conventional commit

Wonderful, this rule succeeded.

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

  • title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert|release)(?:\(.+\))?:

@jakelorocco
Copy link
Contributor

Thanks @Kemalau; I've pinged this issue in another PR that one of our docs maintainers opened to fix this issue in a different way. I think your solution is good; we just need to add a rule to prevent merges with this syntax in the future. We'll see what they say in the other PR.

@planetf1
Copy link
Contributor

Thanks for PR @Kemalau . The intent of the PR looks good - aligned with issue.
I'm suggestionwe merge #658 anyway to get docs working, but also it adds a detection tool.
We'll review this pr (I can't look more until tomorrow) and if good can merge to fix the underlying issue
We already have another issue open to move to hard failures, once the docs are running through the pipeline cleanly, we we prevent future issues.

@planetf1
Copy link
Contributor

Note - We have a template we use for PRs. I suggest copying the format from another PR (use the same comment line at top, section headings, and check boxes from another PR marked as Misc.) Save it. then merge your text back into that format afterwards. That should make the PR Box go green.

@planetf1
Copy link
Contributor

Heads up: 91-file surface area will conflict with #653 on backend files. Recommend merging after #653 and rebasing.

@planetf1 planetf1 added the documentation Improvements or additions to documentation label Mar 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: replace RST double-backtick notation with single backticks in source docstrings

3 participants