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
✗ HARD-BROKEN BUILD — fix this first; the rest of the log is unreliable.  signal: extension-error    Extension error (sphinx.ext.autosummary)!     Traceback    =========   hint: the named module is usually a DECOY. autosummary imports every documented object at builder-inited, so the real cause is typically an unrelated module whose import chain breaks under autodoc_mock_imports (a dep mocked for the doc build -- numpy/pandas/etc. -- but used at import time), aborting a shared import (in Ray, ray.air imports ray.data). Trace the import to the offending eager import and make it lazy; the named module is just the first to trip it.  The warning list below is incomplete until this is fixed. Build: state=Finished  success=False  exit=1 Partial findings (warning pass did not complete) (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 the hard-broken build above, then rebuild and re-run.