About fix-sphix-docs
fix-sphix-docs is a skill for iterating on Sphinx documentation builds and attempting to fix straightforward errors and warnings. It is aimed at documentation maintainers, limits build waiting time, and avoids generated RST files.
Key features
- 01Run a Sphinx HTML build
- 02Limit build wait time
- 03Inspect build errors and warnings
- 04Skip autogenerated RST files
- 05Report changes and ask about opening a PR
Use cases
- 01Diagnose Sphinx documentation build issues
- 02Fix straightforward documentation warnings
- 03Inspect output before a build times out
- 04Prepare a documentation-fix PR
Install
Copy the command and run it in a terminal.
$
npx skills add https:/After installing, type/fix-sphix-docsin Claude Code to confirm it loaded.
Details
From the project READMEFix errors and warnings in Sphinx docs build
This skill iterates over Sphinx docs build and attempt to fix easily addressable errors and warnings.
Steps
- Run Sphinx build:
(source ./.venv/bin/activate && cd ./docs/ && make html), but with a twist: figure out how to abort after 60 second do not try to wait for the full build takes too long. - Check the output warnings and errors you could attempt to fix. DON'T TOUCH AUTO GENERATED RST FILES. These are in
_autosummaryfolders like_autosummary_d2. These folders will be recreated by user with a special command you do not know. - Report made changes
- Ask a permission to open a PR
Comments
Markdown supported