fix-sphix-docs

What it does

This skill automatically identifies and corrects errors in Sphinx documentation files. It scans for broken links, missing references, and syntax issues to ensure your technical docs are accurate and buildable.

When to use it

• You have recently updated code or API definitions and need to verify that existing documentation still references them correctly.
• Your CI/CD pipeline is failing due to Sphinx build errors related to missing modules or invalid link targets.
• You want to clean up legacy documentation before publishing a new version of your project.

Key capabilities

• Scans .rst and .md files for broken cross-references and hyperlinks.
• Detects undefined roles, directives, and labels within the Sphinx configuration.
• Generates a report highlighting specific line numbers and types of errors found.

Example prompts

• "Run fix-sphix-docs on my docs/ directory to find any broken links before I deploy."
• "Check if the new API endpoint added in version 2.0 is correctly documented without errors."
• "Scan the entire documentation tree and list all missing references that are causing build failures."

Tips & gotchas

Ensure your Sphinx configuration file (conf.py) is up to date, as the skill relies on it to validate references accurately. This tool focuses on structural integrity; it does not rewrite content for clarity or style.