Skip to content

docs: RST double-backtick notation breaks API cross-reference links #656

Description

@planetf1

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 runs
  • validate.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).

Metadata

Metadata

Assignees

Labels

bugSomething isn't workingdocumentationImprovements or additions to documentation

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions