sphinx-fix

Diagnose a failing Ray Sphinx / Read the Docs documentation build. Parses the Sphinx warning stream (an RtD build log, a local build, or pasted text), classifies each warning against a rules table, and proposes the canonical fix in severity-tier order. Detects a hard-broken build, segregates known-benign suppressed classes, and lists every unclassified warning. Use when a `docs/readthedocs.com:anyscale-ray` check fails, when asked "why is the docs build failing?" or "what warning is breaking this PR?", or to turn a Sphinx warning dump into an ordered fix list.

Install
npx skills add 'https://github.com/ray-project/ray/tree/master/doc/.claude/skills/sphinx-fix'
Download bundle ↓
master · 39882c6Scanned 2026-09-17

Contributors

GitHub-linked commit authors for this SKILL.md at the saved revision. Co-authors and history before file renames are not included.

File history ↗
View on GitHub
← Back to SKILL.md
Build: state=Finished  success=False  exit=1  build finished with problems, 4 warnings. Root-cause groups (1) — a structural root masks a downstream flood; fix the root, rebuild, and the masked references clear together:  ROOT [T2] autosummary-stub-not-found — ray.data.Dataset.* (2 stubs not generated, masking 2 downstream references)        where:  doc/source/apis/data/ray.data.Dataset.rst:20        stubs:  ray.data.Dataset.map_batches, ray.data.Dataset.map        fix:    Do not fix per entry when the failure is in bulk. Determine scope first: many missing stubs sharing a module prefix point at one root -- confirm the module imports under the build's mock set (autodoc_mock_imports) and that autosummary_generate is on; when an API-ref restructuring is in flight, the correct move may be to revert or repair the file moves rather than edit each entry. A lone missing stub means the member no longer exists -- update or drop the autosummary entry.        safety: judgment (needs your call)    masks 2 downstream py:* reference(s) — collapsed (full list in --json):          doc/source/apis/data/aggregate.rst:6  ray.data.Dataset.map_batches          doc/source/apis/data/aggregate.rst:6  ray.data.Dataset.map Findings (0):  (none) Unclassified (0) — no rule matched; resolve with the user, then file a skill-improvement ticket to add a rule: Suppressed (0) — known-benign, not actionable: Next: fix Tier 2 first (it masks others), then rebuild and re-run — do not assume one pass is complete.