[doc] Add sphinx-fix skill to classify doc-build warnings

[dstrodtman]

Why

The Ray docs build with fail_on_warning: true, so any single Sphinx warning fails the build. The expensive part of a docs change is usually not the edit — it's locating the warning, a manual, token-heavy chain (one RST→MyST conversion tier took three ~6-minute Read the Docs cycles just to find the failure). These failures are a small, classifiable set with mechanical, canonical fixes.

What

Adds sphinx-fix, a deterministic, read-only Claude Code skill under doc/.claude/skills/ that turns a Sphinx warning stream into a severity-ordered list of findings, each with its canonical fix:

• rules.yaml — the canonical category/signature → cause → fix table (10 seed rules plus known-benign suppressions). It is the single source the rst-to-myst skill now points at for the shared MyST link classes.
• sphinx_fix.py — a stdlib-only engine (prefers PyYAML, falls back to a bundled parser so it runs anywhere) that parses the warning stream (a Read the Docs log, a local build, or pasted text), classifies each warning, detects a hard-broken build first, triages by severity tier (fatal → structural → plain), segregates suppressed classes, and lists every unclassified warning so the table can grow from real misses. v0 is human-in-the-loop: it proposes fixes and never edits files.
• SKILL.md — when and how to use it, the severity-tier iterate loop, applying fixes, and the unclassified→follow-up feedback loop.
• Tests — eight fixtures plus golden files, run via python doc/.claude/skills/sphinx-fix/sphinx_fix.py --selftest (which also cross-checks the fallback parser against PyYAML).

The new files live under doc/.claude/skills/ and do not participate in the Sphinx build or doctest (those globs start at doc/source/). Verified end-to-end against a real Read the Docs build log.

Notes for reviewers

• Stacked on [doc] Add rst-to-myst conversion skill #64135 (the rst-to-myst skill, which introduces doc/.claude/skills/). This draft's diff includes that PR until it merges; I'll rebase onto master for a clean diff and mark ready then.
• Kept as a draft until [doc] Add rst-to-myst conversion skill #64135 lands.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces a new documentation migration and diagnostic toolset, including a skill for converting reStructuredText to MyST Markdown, a diagnostic skill for Sphinx build warnings, a rules configuration file, and a Python script (sphinx_fix.py) to classify and suggest fixes for Sphinx warnings. The review feedback highlights a potential crash in the fallback YAML parser when processing empty or whitespace-only inputs, and recommends explicitly specifying encoding='utf-8' across multiple read_text() calls to ensure cross-platform compatibility on Windows.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

If the input text is empty or contains only comments/whitespace, items will be empty. This causes peek() to return None, leading to a TypeError: 'NoneType' object is not subscriptable when cur[1] is accessed in parse_node. Adding a guard to return an empty dictionary when items is empty prevents this crash.

def _yaml_fallback(text: str):
    items: list[list] = []
    for raw in text.split('\n'):
        content = _strip_comment(raw)
        if not content.strip():
            continue
        indent = len(content) - len(content.lstrip(' '))
        items.append([indent, content.strip()])
    if not items:
        return {}
    pos = [0]

[gemini-code-assist]

Specify encoding='utf-8' when calling read_text() to prevent potential UnicodeDecodeError crashes on platforms where the default system encoding is not UTF-8 (such as Windows).

Suggested change

	text = path.read_text()
	text = path.read_text(encoding='utf-8')

[gemini-code-assist]

Specify encoding='utf-8' when calling read_text() to ensure consistent cross-platform behavior and avoid UnicodeDecodeError on Windows.

Suggested change

	text = rules_path.read_text()
	text = rules_path.read_text(encoding='utf-8')

[gemini-code-assist]

Specify encoding='utf-8' when calling read_text() to ensure consistent cross-platform behavior and avoid UnicodeDecodeError on Windows.

            fx.read_text(encoding='utf-8'), rules, supps, versions=None, baseline=baseline

[gemini-code-assist]

Specify encoding='utf-8' when calling read_text() to ensure consistent cross-platform behavior and avoid UnicodeDecodeError on Windows.

Suggested change

	want = gold.read_text()
	want = gold.read_text(encoding='utf-8')

[gemini-code-assist]

Specify encoding='utf-8' when calling read_text() to ensure consistent cross-platform behavior and avoid UnicodeDecodeError on Windows.

Suggested change

	return Path(src).read_text()
	return Path(src).read_text(encoding='utf-8')

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{Reviewed by Cursor Bugbot for commit bd73add. Configure here.}

[cursor]

Verdict ignores unclassified warnings

Medium Severity

When a report has both classified findings and unclassified warnings, _verdict returns only the findings message (including “re-run to confirm clean”) because it checks report.findings before report.unclassified. Unclassified items still fail the docs build but are omitted from the closing guidance.

 

^{Reviewed by Cursor Bugbot for commit bd73add. Configure here.}