Skip to content

[doc] Convert ray-contribute getting-involved, development, and involvement to MyST#64136

Open
dstrodtman wants to merge 1 commit into
ray-project:masterfrom
dstrodtman:djs-260615-raycontrib-md-tierD
Open

[doc] Convert ray-contribute getting-involved, development, and involvement to MyST#64136
dstrodtman wants to merge 1 commit into
ray-project:masterfrom
dstrodtman:djs-260615-raycontrib-md-tierD

Conversation

@dstrodtman

@dstrodtman dstrodtman commented Jun 16, 2026

Copy link
Copy Markdown
Contributor

Description

Convert the final three contributor-facing Developer Guides pages in doc/source/ray-contribute/ from reStructuredText to MyST Markdown, completing the section's migration to MyST (the declared standard for new pages). These are the hub/entry pages — the most coupled in the section.

Pages converted:

  • getting-involved — the contributor hub
  • development — building Ray from source
  • involvement — the community-links partial included by getting-involved

Faithful format conversion only — no content restructuring. Notable handling:

  • development — the sphinx-design .. tab-set:: / .. tab-item:: and two .. dropdown:: blocks become colon-fence directives (::::{tab-set} / :::{tab-item} / :::{dropdown}) so the nested code fences compose cleanly. All 8 cross-reference labels are preserved (building-ray, fork-ray-repo, prepare-venv, python-develop, python-develop-uninstall, build-distributable-wheel, build-ray-image, full-source-build) — referenced internally and from getting-involved.
  • getting-involved — its two .. testcode:: blocks (the canonical pydoc examples) become {testcode}; the page stays excluded from the doctest rule, so its doc/BUILD.bazel exclude entry is updated .rst.md. The .. include:: of involvement becomes {include} involvement.md, and the shared _includes/_latest_contribution_doc.rst banner stays an include via {include} with :parser: rst. The getting-involved label is preserved.
  • involvement — a content partial (no frontmatter); its named-reference links are inlined, which also removes the duplicate on GitHub target it shared with getting-involved.

Companion .claude/ updates point at the new .md paths (root CLAUDE.md, the lint and rebuild skills, the python-guidelines rule). Toctree entries are extensionless and unchanged; .html redirect targets are unaffected.

One forced rendering change: the lettered sub-list (a/b/c) under "Fork the Ray repository" becomes a numbered sub-list (1/2/3), since MyST/CommonMark has no alpha-enumerated lists.

Related issues

None.

Additional information

Verified locally: frontmatter parses; backtick and ::: colon fences balance (60/60 and 10/10); all 9 labels present; {testcode}/{toctree}/{include}/{tab-set}/{tab-item}/{dropdown} counts are exact; no residual RST outside fences; and the blockquote-wrapped code, the Windows nested numbered list, and the python-develop column-0 code-block list all render correctly via markdown-it. The RtD preview build is the authoritative check for the sphinx-design directives and cross-references.

Completes the ray-contribute/ RST→MyST migration (Tier A #64100, Tier B #64111, Tier C #64115, plus the rst-to-myst skill #64135).

Cross-reference fixes (flagged by the initial RtD build): docs.md's link to the renamed getting-involved is now extensionless, and getting-involved's two intra-page section links use MyST #anchor fragments — the original .html#anchor form isn't resolved by MyST and emits myst.xref_missing.

@dstrodtman dstrodtman requested a review from a team as a code owner June 16, 2026 12:17

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request converts several documentation files (development, getting-involved, and involvement) from reStructuredText (.rst) to MyST Markdown (.md) and updates all corresponding references across the repository. The review feedback suggests minor improvements to the newly created Markdown files, specifically correcting a duplicate word typo in involvement.md and using relative anchor links instead of hardcoded .html extensions for self-referential links in getting-involved.md.

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.

researchers, and folks that love machine learning. Here's a list of tips for getting involved with the Ray community:

- Join our [community Slack](https://www.ray.io/join-slack) to discuss Ray!
- Star and follow us on [on GitHub](https://github.com/ray-project/ray).

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

There is a duplicate "on" in "on [on GitHub]". It should be simplified to "on [GitHub]".

Suggested change
- Star and follow us on [on GitHub](https://github.com/ray-project/ray).
- Star and follow us on [GitHub](https://github.com/ray-project/ray).

git pull . upstream/master
```

2. Make sure all existing [tests](getting-involved.html#testing) and [linters](getting-involved.html#lint-and-formatting) pass.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Since this link is self-referential to the same page, you can use relative anchor links (#testing and #lint-and-formatting) instead of hardcoding the .html filename extension.

Suggested change
2. Make sure all existing [tests](getting-involved.html#testing) and [linters](getting-involved.html#lint-and-formatting) pass.
2. Make sure all existing [tests](#testing) and [linters](#lint-and-formatting) pass.

@dstrodtman dstrodtman force-pushed the djs-260615-raycontrib-md-tierD branch from ffaa723 to ce97049 Compare June 16, 2026 12:34
…vement to MyST

## Why

`doc/.claude/CLAUDE.md` declares MyST Markdown the standard for new doc
pages, and a lint check rejects newly added `.rst`. This completes the
`ray-contribute/` migration with the hub/entry pages — the most coupled
ones, with sphinx-design tabs/dropdowns, includes, and `.claude/` path
references.

## What

Convert the final three Developer Guides pages from reStructuredText to
MyST Markdown, matching the conventions in `docs.md` / `agent-development.md`:

- `getting-involved` (the contributor hub)
- `development` (building Ray from source)
- `involvement` (the community-links partial included by `getting-involved`)

Faithful format conversion only, no content restructuring. Notable handling:

- `development`'s sphinx-design `.. tab-set::`/`.. tab-item::` and two
  `.. dropdown::` blocks become colon-fence directives (`::::{tab-set}` /
  `:::{tab-item}` / `:::{dropdown}`) so the nested code fences compose
  cleanly. All 8 labels are preserved (`building-ray`, `fork-ray-repo`,
  `prepare-venv`, `python-develop`, `python-develop-uninstall`,
  `build-distributable-wheel`, `build-ray-image`, `full-source-build`) —
  referenced internally and from `getting-involved`.
- `getting-involved`'s two `.. testcode::` blocks (the canonical pydoc
  examples) become `{testcode}`; the page stays excluded from the doctest
  rule, so its `doc/BUILD.bazel` exclude entry is updated `.rst` → `.md`.
  Its `.. include::` of `involvement` becomes `{include} involvement.md`,
  and the shared `_includes/_latest_contribution_doc.rst` banner stays an
  include via `{include}` with `:parser: rst`.
- `involvement` is a content partial (no frontmatter); its named-reference
  links are inlined, which also removes the duplicate `on GitHub` target it
  shared with `getting-involved`.

Companion `.claude/` updates point at the new `.md` paths (root `CLAUDE.md`,
the `lint` and `rebuild` skills, the python-guidelines rule). Toctree entries
are extensionless and unchanged; `.html` redirect targets are unaffected.

One forced rendering change: the lettered sub-list (a/b/c) under "Fork the Ray
repository" becomes a numbered sub-list (1/2/3), since MyST/CommonMark has no
alpha-enumerated lists.

Signed-off-by: Douglas Strodtman <douglas@anyscale.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@dstrodtman dstrodtman force-pushed the djs-260615-raycontrib-md-tierD branch from ce97049 to abab74c Compare June 16, 2026 13:08
@ray-gardener ray-gardener Bot added docs An issue or change related to documentation core Issues that should be addressed in Ray Core labels Jun 16, 2026
@dstrodtman dstrodtman added the go add ONLY when ready to merge, run all tests label Jun 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

core Issues that should be addressed in Ray Core docs An issue or change related to documentation go add ONLY when ready to merge, run all tests

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant