Fix Sphinx Linkcheck
Testing & Qualityfix-sphinx-linkcheckFix 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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
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
- Identify failing links from
doc-linkcheckoutput. - 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.
- Preferred:
- For missing anchors, replace with a currently working URL/anchor from upstream docs.
- For stable, known 403 responses from external sites, add a focused regex to
doc/sphinx/conf.pylinkcheck_ignore. - 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.