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, 1 warning. Findings (1):  Tier 3 — warnings:    [T3] py-xref-target-not-found  python/ray/train/collective/__init__.py:docstring of ray.train.collective.broadcast_from_rank_zero:          msg:    py:exc reference target not found: pickle.PicklingError          fix:    Check for a co-occurring tier-2 autosummary-stub-not-found or tier-1 import abort for the same module first. If present, fix that root (up to and including reverting an in-progress API-ref restructuring) and rebuild -- the flood clears at once. Only when the build is otherwise healthy is the reference itself wrong: repoint to the correct dotted path, or fix the intersphinx target for a stdlib/third-party name. For a third-party target that DOES exist upstream, suspect a stale committed inventory snapshot: upstream added the symbol after doc/source/_intersphinx/<project>.inv was last refreshed. Fix by running `python doc/source/_intersphinx/refresh.py <project>` and committing the updated .inv, not by editing the reference.          safety: judgment (needs your call) 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: apply the fixes above, then rebuild and re-run to confirm clean.