From 35805cf43c9cf32b5e07ef7f0a63ce4f563ea17c Mon Sep 17 00:00:00 2001 From: Douglas Strodtman Date: Fri, 8 May 2026 09:15:14 -0400 Subject: [PATCH 1/6] [doc] add agent context for Ray documentation ## Why Ray's per-library `.claude/CLAUDE.md` convention is in place for `data`, `serve`, `train`, `tune`, `rllib`, and `src/ray`. `doc/` is missing this file. Agents working on docs have no in-repo signal about how Ray's CI is configured for documentation changes or how to scope PRs to land cleanly. ## What Adds `doc/.claude/CLAUDE.md` with concise pointers to: - How `.buildkite/test.rules.txt` maps file patterns to tag sets, and which patterns the `doc` tag covers (post-#63132 shape). - Scope discipline for docs-only PRs: take the lightest path; don't bundle in non-doc changes. - When to revise test rules vs. work around them (precedent: #63132). - Existing skills (`/lint`, `/fetch-buildkite-logs`, `/rebuild`). Under 50 lines per the existing per-library convention. ## Context Tracked under `DOC-879` in anyscale/docs Jira (private). Captures the test-rule discipline that emerged during the docs-infra mapping work in #63132. Co-Authored-By: Claude Opus 4.7 (1M context) Signed-off-by: Douglas Strodtman --- doc/.claude/CLAUDE.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 doc/.claude/CLAUDE.md diff --git a/doc/.claude/CLAUDE.md b/doc/.claude/CLAUDE.md new file mode 100644 index 000000000000..49c4e74da78a --- /dev/null +++ b/doc/.claude/CLAUDE.md @@ -0,0 +1,32 @@ + + + +# Ray Documentation + +Sphinx documentation built by Read the Docs and served at `docs.ray.io`. Build pipeline: `.buildkite/doc.rayci.yml`. + +## How CI is configured + +`.buildkite/test.rules.txt` maps file-change patterns to tag sets, and tags drive which CI suites run. The `doc` tag covers content under `doc/`, `doc/requirements-doc.txt`, `.vale.ini`/`.vale/`, and `.buildkite/doc.rayci.yml`. Docs-only deplock changes (`python/deplocks/docs/*.lock`, `ci/raydepsets/configs/docs.depsets.yaml`) tag to `doc python_dependencies` to skip the full python-deps test set. + +## Scope discipline for PRs + +For docs-only fixes, take the lightest path: + +- Touch only files mapped to the `doc` tag. +- Don't bundle in a non-doc change "while you're at it" — that change pulls its own (often expensive) test set into the PR. +- If a docs change requires a non-doc change to land cleanly (e.g., autodoc references a renamed symbol), land them in the larger non-doc PR, not a docs-led PR. + +For generated API docs that depend on Python source under `python/ray/...`, expect broader test runs. That's correct, not a misconfiguration. + +## When to revise the test rules + +If a docs-only PR hits unnecessarily broad tests, file a `.buildkite/test.rules.txt` PR (precedent: #63132) instead of working around it. Quick check: does the file change affect any non-`doc` build artifact, runtime behavior, or API surface? If no, tag it `doc`. + +## Skills + +- `/lint` — run linters on modified files. +- `/fetch-buildkite-logs` — pull build logs for CI failures. +- `/rebuild` — guided rebuild after C++/Cython changes. + +See top-level `.claude/CLAUDE.md` for the full skill index. From d39c0fc79684f0cd3cd07bc7a97e48637f6e81fb Mon Sep 17 00:00:00 2001 From: Douglas Strodtman Date: Fri, 8 May 2026 10:06:01 -0400 Subject: [PATCH 2/6] Apply suggestion from @dstrodtman Signed-off-by: Douglas Strodtman --- doc/.claude/CLAUDE.md | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/.claude/CLAUDE.md b/doc/.claude/CLAUDE.md index 49c4e74da78a..e58ff3fce2b0 100644 --- a/doc/.claude/CLAUDE.md +++ b/doc/.claude/CLAUDE.md @@ -27,6 +27,5 @@ If a docs-only PR hits unnecessarily broad tests, file a `.buildkite/test.rules. - `/lint` — run linters on modified files. - `/fetch-buildkite-logs` — pull build logs for CI failures. -- `/rebuild` — guided rebuild after C++/Cython changes. See top-level `.claude/CLAUDE.md` for the full skill index. From e90eec769346fe0dae0bf8473d589ddd35cbf276 Mon Sep 17 00:00:00 2001 From: Douglas Strodtman Date: Fri, 15 May 2026 22:13:33 -0400 Subject: [PATCH 3/6] [doc] document MyST-only policy for new pages Follows up ray-project/ray#63057 (ban new .rst lint check) by documenting the policy in two places contributors and agents will read first: - doc/README.md: new "Contributing new documentation pages" section. - doc/.claude/CLAUDE.md: new "File format for new pages" section, including the deliberate `git mv` allowance for renames and directory reorganization. Signed-off-by: Douglas Strodtman --- doc/.claude/CLAUDE.md | 4 ++++ doc/README.md | 6 ++++++ 2 files changed, 10 insertions(+) diff --git a/doc/.claude/CLAUDE.md b/doc/.claude/CLAUDE.md index e58ff3fce2b0..a269df2b0421 100644 --- a/doc/.claude/CLAUDE.md +++ b/doc/.claude/CLAUDE.md @@ -5,6 +5,10 @@ Sphinx documentation built by Read the Docs and served at `docs.ray.io`. Build pipeline: `.buildkite/doc.rayci.yml`. +## File format for new pages + +Author new files under `doc/source/` as MyST Markdown (`.md`). A lint check rejects newly added `.rst` files. Edits to existing `.rst` files are not flagged. `git mv` is not flagged for any rename, which covers file renames and directory reorganization. This is deliberate, to keep reorganization and agent-driven moves unblocked. + ## How CI is configured `.buildkite/test.rules.txt` maps file-change patterns to tag sets, and tags drive which CI suites run. The `doc` tag covers content under `doc/`, `doc/requirements-doc.txt`, `.vale.ini`/`.vale/`, and `.buildkite/doc.rayci.yml`. Docs-only deplock changes (`python/deplocks/docs/*.lock`, `ci/raydepsets/configs/docs.depsets.yaml`) tag to `doc python_dependencies` to skip the full python-deps test set. diff --git a/doc/README.md b/doc/README.md index 5d477fa1f6c1..85b643934410 100644 --- a/doc/README.md +++ b/doc/README.md @@ -2,6 +2,12 @@ Repository for documentation of the Ray project, hosted at [docs.ray.io](https://docs.ray.io). +## Contributing new documentation pages + +Author new documentation files under `doc/source/` as MyST Markdown (`.md`), not reStructuredText (`.rst`). A lint check rejects newly added `.rst` files. Edits to existing `.rst` files continue to work. `git mv` is not flagged for any rename, which covers file renames and directory reorganization. + +MyST is a Markdown superset that supports the Sphinx directives used throughout the docs. See the [MyST Parser documentation](https://myst-parser.readthedocs.io/) for syntax reference. + ## Installation To build the documentation, make sure you have `ray` installed first. From 780eff530418c9c18468f1a760f703418b7b3e6a Mon Sep 17 00:00:00 2001 From: Douglas Strodtman Date: Mon, 18 May 2026 09:31:32 -0400 Subject: [PATCH 4/6] gitignore claude worktrees Signed-off-by: Douglas Strodtman --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 462fc318b1dd..b134dfa0b8fa 100644 --- a/.gitignore +++ b/.gitignore @@ -253,3 +253,4 @@ CLAUDE.local.md # Worktrees .worktrees/ +.claude/workstrees/ \ No newline at end of file From 08ed644f59b7fb165595e6d0fd24d86bdf146b46 Mon Sep 17 00:00:00 2001 From: Douglas Strodtman Date: Mon, 18 May 2026 09:50:18 -0400 Subject: [PATCH 5/6] fix gitignore: .claude/worktrees not .claude/workstrees The previous commit had a typo (workstrees) so the directory was not actually ignored. Also adds a trailing newline. Co-Authored-By: Claude Opus 4.7 (1M context) Signed-off-by: Douglas Strodtman --- .gitignore | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index b134dfa0b8fa..665e88edefd3 100644 --- a/.gitignore +++ b/.gitignore @@ -253,4 +253,4 @@ CLAUDE.local.md # Worktrees .worktrees/ -.claude/workstrees/ \ No newline at end of file +.claude/worktrees/ From bf946155f2701122201c5fb44210aa9c85eba297 Mon Sep 17 00:00:00 2001 From: Douglas Strodtman Date: Mon, 18 May 2026 13:14:40 -0400 Subject: [PATCH 6/6] [doc][DOC-943] add follow-up rules to doc agent context Add four sections capturing authoring gotchas surfaced during the DOC-932 dependency-upgrade probe work and during PR review of the initial agent-context add (#63227): - **DCO sign-off.** Every commit on a ray-project/ray PR needs a Signed-off-by trailer or the DCO check fails the PR. - **Cross-references between .md and .rst sources.** Use the {doc} role, not bare [text](path.md), because MyST-Parser 2.0's cross-extension resolution emits myst.xref_missing on .rst targets, which fail_on_warning turns into a build failure. - **Comparing PR previews against /en/master vs /en/latest.** Use /en/master to isolate regressions attributable to the PR. /en/latest mixes in unreleased upstream churn. - **Editing the docs lockfile.** Hand-edit additive bumps; regenerate via raydepsets when a package's direct deps change. Precedent: #63344 caught stale via-comments after the pydata-sphinx-theme bump dropped packaging as a direct dep. Folds the net-new content from #63354 (doc-943-claude-md-followups) into this PR. Co-Authored-By: Claude Opus 4.7 (1M context) Signed-off-by: Douglas Strodtman --- doc/.claude/CLAUDE.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/doc/.claude/CLAUDE.md b/doc/.claude/CLAUDE.md index a269df2b0421..4a44a5c0951e 100644 --- a/doc/.claude/CLAUDE.md +++ b/doc/.claude/CLAUDE.md @@ -23,10 +23,29 @@ For docs-only fixes, take the lightest path: For generated API docs that depend on Python source under `python/ray/...`, expect broader test runs. That's correct, not a misconfiguration. +## DCO sign-off + +Every commit on a `ray-project/ray` PR needs a `Signed-off-by:` trailer (Developer Certificate of Origin). Pass `--signoff` to `git commit`, or `git commit --amend --signoff` to fix an unsigned commit. The DCO GitHub check fails the PR otherwise. + ## When to revise the test rules If a docs-only PR hits unnecessarily broad tests, file a `.buildkite/test.rules.txt` PR (precedent: #63132) instead of working around it. Quick check: does the file change affect any non-`doc` build artifact, runtime behavior, or API surface? If no, tag it `doc`. +## Cross-references between .md and .rst sources + +When linking from .md to a doc whose source is .rst, use the {doc} role, not a bare `[text](path.md)` link: `` {doc}`Ray documentation home page ` ``. MyST-Parser 2.0 has a cross-extension resolution bug — a bare `[text](path.md)` link to an .rst source emits `myst.xref_missing`, which `fail_on_warning: true` in `.readthedocs.yaml` turns into a build failure. + +## Comparing PR previews against `/en/master` vs `/en/latest` + +For regression checks, compare a PR preview against `/en/master` — it's the docs build of the same master state your PR branches from, so byte-level content diffs against master are attributable to the stack. `/en/latest` is the last tagged release and lags master by every unreleased commit, so diffs there mix in upstream feature work and don't isolate regressions. Use `/en/latest` only to inventory net-new content since the last release. + +## Editing the docs lockfile + +`doc/requirements-doc.txt` is source of truth; `python/deplocks/docs/docbuild_depset_py3.10.lock` is regenerated by raydepsets, and CI's `raydepsets --check` enforces consistency. + +- Additive packages or version bumps with unchanged dep trees: hand-edit the package's entry block plus its via comments. Precedent: #63130. +- Version bumps that change a package's direct deps (gaining or losing requirements): regenerate via `bazelisk run //ci/raydepsets:raydepsets -- build ci/raydepsets/configs/docs.depsets.yaml`. Hand-edits miss transitive churn — precedent: #63344 caught a stale `# via pydata-sphinx-theme` line under `packaging` after the theme dropped that dep. + ## Skills - `/lint` — run linters on modified files.