diff --git a/.gitignore b/.gitignore index 462fc318b1dd..665e88edefd3 100644 --- a/.gitignore +++ b/.gitignore @@ -253,3 +253,4 @@ CLAUDE.local.md # Worktrees .worktrees/ +.claude/worktrees/ diff --git a/doc/.claude/CLAUDE.md b/doc/.claude/CLAUDE.md new file mode 100644 index 000000000000..4a44a5c0951e --- /dev/null +++ b/doc/.claude/CLAUDE.md @@ -0,0 +1,54 @@ + + + +# Ray Documentation + +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. + +## 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. + +## 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. +- `/fetch-buildkite-logs` — pull build logs for CI failures. + +See top-level `.claude/CLAUDE.md` for the full skill index. 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.