OpenParable
Skip to content
← Back to skills

Fix Sphinx Linkcheck

Testing & Quality
fix-sphinx-linkcheck

Fix Sphinx Linkcheck is an Agent Skill for testing & quality published in the canonical/mir repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Fix Sphinx linkcheck failures in Mir docs: disambiguate ambiguous internal links, replace stale external anchors, add known 403-only URLs to linkcheck_ignore, and verify with doc-clean-doc, doc-html, doc-linkcheck targets.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/canonical/mir/blob/HEAD/.github/skills/fix-sphinx-linkcheck/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/fix-sphinx-linkcheck, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Fix Sphinx Linkcheck

Use this workflow when CI reports Sphinx linkcheck failures in the Mir docs.

Reference for destination resolution and disambiguation: https://myst-parser.readthedocs.io/en/latest/syntax/cross-referencing.html#default-destination-resolution

Steps

  1. Identify failing links from doc-linkcheck output.
  2. For ambiguous internal references (for example multiple matches for one label), disambiguate with Sphinx's standard-domain label role.
    • Preferred: {ref}`my-label` .
    • Example: use {ref}`release-notes` instead of doc/path-style links.
  3. For missing anchors, replace with a currently working URL/anchor from upstream docs.
  4. For stable, known 403 responses from external sites, add a focused regex to doc/sphinx/conf.py linkcheck_ignore.
  5. Verify in sequence:
cmake -B ~/build .
cmake --build ~/build --target doc-clean-doc
cmake --build ~/build --target doc-html
cmake --build ~/build --target doc-linkcheck

Rules

  • Keep edits minimal and local to the reported failures.
  • Prefer {ref}`label` links for internal docs.
  • Prefer explicit targets created with (my-label)= over implicit heading anchors.
  • Keep ignore regexes narrowly scoped to avoid masking real failures.