Problem
Several API doc pages display cross-references as raw markdown text instead of clickable links.
Example — mellea.backends.backend:
FormatterBackend extends the abstract ``Backend`` with a ``ChatFormatter``…
The backtick-wrapped link text is rendered as inline code containing raw link syntax rather than a rendered link.
Root cause
91 source files use RST-style ````Symbol```` double-backtick notation in docstrings (Sphinx convention). The `add_cross_references` build step matches the inner single-backtick boundary and generates a link wrapped in an extra code span:
```
Backend → [Backend](url) ← Mintlify renders as code, not a link
```
Fix (this PR)
decorate_api_mdx.py: new normalize_rst_backticks() pass converts ``x`` → `x` in MDX prose before cross-reference substitution runsvalidate.py: new validate_rst_docstrings(source_dir) warns on RST notation without blocking the build
Validation output (CI)
Running `uv run poe apidocs-validate` with `--source-dir mellea` now reports:
✅ RST docstrings: FAIL
992 occurrences found
Overall build remains green — this is a warning only.
Follow-up
See #657 — convert ``Symbol`` → `Symbol` across source files (91 files, 992 occurrences).
Problem
Several API doc pages display cross-references as raw markdown text instead of clickable links.
Example —
mellea.backends.backend:The backtick-wrapped link text is rendered as inline code containing raw link syntax rather than a rendered link.
Root cause
91 source files use RST-style ````Symbol```` double-backtick notation in docstrings (Sphinx convention). The `add_cross_references` build step matches the inner single-backtick boundary and generates a link wrapped in an extra code span:
```
Backend→[Backend](url)← Mintlify renders as code, not a link```
Fix (this PR)
decorate_api_mdx.py: newnormalize_rst_backticks()pass converts ``x`` → `x` in MDX prose before cross-reference substitution runsvalidate.py: newvalidate_rst_docstrings(source_dir)warns on RST notation without blocking the buildValidation output (CI)
Running `uv run poe apidocs-validate` with `--source-dir mellea` now reports:
Overall build remains green — this is a warning only.
Follow-up
See #657 — convert ``Symbol`` → `Symbol` across source files (91 files, 992 occurrences).