docs: fix RST double-backtick notation breaking API cross-reference links

[planetf1]

docs: fix RST double-backtick notation breaking API cross-reference links

Type of PR

• Bug Fix
• New Feature
• Documentation
• Other

Description

• Link to Issue: Fixes docs: RST double-backtick notation breaks API cross-reference links #656, follow-up: docs: replace RST double-backtick notation with single backticks in source docstrings #657

API doc pages were displaying cross-references as raw markdown text rather than clickable links. For example, on mellea.backends.backend, the class description rendered as:

FormatterBackend extends the abstract [`Backend`](../core/backend#class-backend)…

— the link syntax appeared as inline code rather than a hyperlink.

Root cause: 91 source files use RST-style ``Symbol`` double-backtick notation (Sphinx convention). The add_cross_references build step matched the inner backtick boundary and generated a link wrapped in an extra code span:

``Backend``  →  `[`Backend`](url)`   ← renders as code, not a link

Fix: A new normalize_rst_backticks() pass in decorate_api_mdx.py converts ``x`` → `x` in MDX prose before add_cross_references runs. A new validate_rst_docstrings() check in validate.py detects remaining occurrences and reports them as a build warning (does not fail the build).

The 992 occurrences across 91 source files are tracked for cleanup in #657.

CI validation output after this fix:

✅ Source links:      PASS
✅ Coverage:          PASS
✅ MDX syntax:        PASS
✅ Internal links:    PASS
✅ Anchor collisions: PASS
⚠️ RST docstrings:   WARN — 992 occurrences across 91 files (cleanup: #657)

Overall: ✅ PASS

Testing

• Tests added to the respective file if code was changed
• New code has 100% coverage if code was added
• Ensure existing tests and github automation passes (a maintainer will kick off the github automation when the rest of the PR is populated)

[mergify]

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)(?:\(.+\))?:

[psschwei]

need to decide if we want to merge this one or #659

[jakelorocco]

@planetf1, is there a ruff linting rule we can activate to prevent future misuses? If so, I think we should #659 and then just enable the rule / add a quality check instead of doing the change at doc compile time.

[planetf1]

I'm looking at the other PR which is indeed appropriate to fix.

There's 2 issues currently - short term/proper fix - this was to avoid risk/approval and get broken doc fixed quickly since we published it a few hours ago.

I would recommend we merge this issue in any case - it's not inconsistent in any way, and also adds a validation check for bad links. This is currently a soft check so after merge will report the RST issues.

Then if we merge #659 we'll see that validation drop by 0

We already have an issue open to move soft fail to hard fail in #f616 (this should include seeing if any parts can be replaced/augmented by ruff checks)

The benefit #659 brings is it's another step completed quickly :-)

So I see a progression here.. we get better step by step :-)

[planetf1]

Minor: generate_report() docstring not updated for the new rst_docstring_errors parameter. Otherwise looks clean.

[planetf1]

re: above -- docstring fixed