Skip to content

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

@planetf1

Description

@planetf1

Context

Follows from #656 (build-time fix for broken cross-reference links).

The root cause is RST-style ````Symbol```` notation in docstrings across the codebase. The build pipeline now auto-corrects this at generation time, but the source should be cleaned up to use standard Markdown/Google-style single backticks.

Scope

91 files, 992 occurrences in `mellea/` and `cli/`.

Detection: run the validator with `--source-dir mellea` — reports all occurrences as warnings.

uv run python tooling/docs-autogen/validate.py docs/docs/api \
    --source-dir mellea --skip-coverage

Example (before/after):

```python

Before (RST)

"""FormatterBackend extends the abstract Backend with a ChatFormatter."""

After (Markdown/Google)

"""FormatterBackend extends the abstract Backend with a ChatFormatter."""
```

Task

Do a bulk find-and-replace of ````word```` → ``word`` throughout `mellea/` and `cli/`. Verify the validator reports 0 warnings afterward.

When complete, the normalize_rst_backticks() pass in decorate_api_mdx.py can optionally be removed (or left as a safety net).

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationgood first issueGood for newcomers

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions