[doc] add agent context for Ray documentation#63227
Open
dstrodtman wants to merge 7 commits into
Open
Conversation
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request introduces a new CLAUDE.md file in the doc/ directory to provide context and guidelines for AI agents working on Ray documentation. The reviewer suggested removing the /rebuild skill from the documentation-specific instructions to maintain focus on documentation tasks and avoid misleading agents about the scope of their work.
ray-gardener
Bot
added
docs
## 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-ray-project#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: ray-project#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 ray-project#63132. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Signed-off-by: Douglas Strodtman <douglas@anyscale.com>
Signed-off-by: Douglas Strodtman <douglas@anyscale.com>
Follows up ray-project#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 <douglas@anyscale.com>
Signed-off-by: Douglas Strodtman <douglas@anyscale.com>
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) <noreply@anthropic.com> Signed-off-by: Douglas Strodtman <douglas@anyscale.com>
dstrodtman
force-pushed
the
doc-879-ray-doc-claude-md
branch
from
9306c14 to
08ed644
Compare
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 (ray-project#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: ray-project#63344 caught stale via-comments after the pydata-sphinx-theme bump dropped packaging as a direct dep. Folds the net-new content from ray-project#63354 (doc-943-claude-md-followups) into this PR. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Signed-off-by: Douglas Strodtman <douglas@anyscale.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Ray's per-library
.claude/CLAUDE.mdconvention is in place fordata,serve,train,tune,rllib, andsrc/ray.doc/is missing this file. Agents working on docs (Claude Code sessions, OSS contributors using AI assistants) 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.mdwith concise pointers to:.buildkite/test.rules.txtmaps file patterns to tag sets, and which patterns thedoctag covers (post-[CI] Map docs-infra files to thedoctag #63132 shape).doctag #63132)./lint,/fetch-buildkite-logs,/rebuild).Under 50 lines per the existing per-library convention. Wording can iterate.
Verification
find ray/doc -path '*/.claude/CLAUDE.md'returns the new file.doc/(a session underdoc/source/will pick this up alongside the top-level.claude/CLAUDE.md).Context
Tracked under
DOC-879in anyscale/docs Jira (private). Captures the test-rule discipline that emerged during the docs-infra mapping work in #63132.