[doc] Convert ray-contribute stability, whitepaper, and profiling guides to MyST#64111
[doc] Convert ray-contribute stability, whitepaper, and profiling guides to MyST#64111dstrodtman wants to merge 1 commit into
Conversation
…des 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 continues the
`ray-contribute/` migration with the reference pages that carry
externally-referenced labels and autodoc.
## What
Convert three Developer Guides pages from reStructuredText to MyST
Markdown, matching the conventions in the existing `docs.md` /
`agent-development.md`:
- `stability`
- `whitepaper`
- `profiling`
Faithful format conversion only, no content restructuring — heading
hierarchy is preserved exactly, including `Docstrings` remaining an `h3`
under `Stable` as it renders on master. The three `.. autofunction::`
directives in `stability` are wrapped in `{eval-rst}`, keeping their
`.. _*-api-def:` labels inline so they stay globally referenceable.
All cross-reference labels are preserved exactly: `api-stability`,
`api-stability-alpha`, `api-stability-beta`, `api-stability-stable`,
`public-api-def`, `developer-api-def`, `deprecated-api-def`, `whitepaper`,
and `ray-core-internal-profiling`. These are referenced from observability
docs, `python/ray/util/annotations.py`, `ray-oom-prevention`, and others.
Toctree entries are extensionless and unchanged; `.html` redirect targets
in `doc/redirects/current.yaml` are unaffected.
Signed-off-by: Douglas Strodtman <douglas@anyscale.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request converts several developer documentation files (profiling, stability, and whitepaper) from reStructuredText (.rst) to MyST Markdown (.md) format. The review feedback highlights opportunities to improve the profiling guide by correcting the relative path to the raylet binary, replacing the undefined $PATH_TO_OUTPUT_DIR environment variable with a robust /tmp default to prevent permission errors, and ensuring subsequent commands consistently reference these updated paths.
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.
|
|
||
| ```bash | ||
| # Use the appropriate path. | ||
| RAYLET=ray/python/ray/core/src/ray/raylet/raylet |
There was a problem hiding this comment.
The python directory is located at the root of the Ray repository (i.e., python/ray/...). Using ray/python/... as the path will fail if run from the repository root. Let's update this to the correct relative path.
| RAYLET=ray/python/ray/core/src/ray/raylet/raylet | |
| RAYLET=python/ray/core/src/ray/raylet/raylet |
| RAY_JEMALLOC_CONF=prof:true,lg_prof_interval:33,lg_prof_sample:17,prof_final:true,prof_leak:true,prof_prefix:$PATH_TO_OUTPUT_DIR/jeprof.out \ | ||
| RAY_JEMALLOC_LIB_PATH=$JEMALLOC_DIR/lib/libjemalloc.so \ | ||
| RAY_JEMALLOC_PROFILE=gcs_server \ | ||
| ray start --head |
There was a problem hiding this comment.
Using an undefined environment variable $PATH_TO_OUTPUT_DIR in the prof_prefix configuration will default to writing directly to the root directory (/jeprof.out), which typically fails with a 'Permission denied' error for non-root users. Using /tmp/jeprof.out is a safer and more robust default that works out of the box.
| RAY_JEMALLOC_CONF=prof:true,lg_prof_interval:33,lg_prof_sample:17,prof_final:true,prof_leak:true,prof_prefix:$PATH_TO_OUTPUT_DIR/jeprof.out \ | |
| RAY_JEMALLOC_LIB_PATH=$JEMALLOC_DIR/lib/libjemalloc.so \ | |
| RAY_JEMALLOC_PROFILE=gcs_server \ | |
| ray start --head | |
| RAY_JEMALLOC_CONF=prof:true,lg_prof_interval:33,lg_prof_sample:17,prof_final:true,prof_leak:true,prof_prefix=/tmp/jeprof.out \ | |
| RAY_JEMALLOC_LIB_PATH=$JEMALLOC_DIR/lib/libjemalloc.so \ | |
| RAY_JEMALLOC_PROFILE=gcs_server \ | |
| ray start --head |
|
|
||
| # Check the output files. You should see files with the format of "jeprof.<pid>.0.f.heap". | ||
| # Example: jeprof.out.1904189.0.f.heap | ||
| ls $PATH_TO_OUTPUT_DIR/ |
There was a problem hiding this comment.
Update the directory listing command to match the /tmp output directory suggestion.
| ls $PATH_TO_OUTPUT_DIR/ | |
| ls /tmp/ |
|
|
||
| # Use jeprof to view the profile data. The first argument is the binary of GCS server. | ||
| # Note that you can also use `--pdf` or `--svg` to generate different formats of the profile data. | ||
| jeprof --text $YOUR_RAY_SRC_DIR/python/ray/core/src/ray/gcs/gcs_server $PATH_TO_OUTPUT_DIR/jeprof.out.1904189.0.f.heap |
There was a problem hiding this comment.
Simplify the jeprof command by using the relative path from the repository root and the /tmp output directory, avoiding the need for undefined environment variables.
| jeprof --text $YOUR_RAY_SRC_DIR/python/ray/core/src/ray/gcs/gcs_server $PATH_TO_OUTPUT_DIR/jeprof.out.1904189.0.f.heap | |
| jeprof --text python/ray/core/src/ray/gcs/gcs_server /tmp/jeprof.out.1904189.0.f.heap |
ray-gardener
Bot
added
docs
2 participants
Description
Convert three contributor-facing Developer Guides reference pages in
doc/source/ray-contribute/from reStructuredText to MyST Markdown, matching the conventions already used bydocs.mdandagent-development.md. Continues the in-progress migration of the section to MyST (the declared standard for new pages).Pages converted:
stabilitywhitepaperprofilingFaithful format conversion only — no content restructuring. Heading hierarchy is preserved exactly, including
Docstringsremaining anh3underStable(unchanged from master). The three.. autofunction::directives instabilityare wrapped in{eval-rst}, with their.. _*-api-def:labels kept inline so the targets stay globally referenceable.Cross-reference labels preserved exactly (these have external callers — observability docs,
python/ray/util/annotations.py,ray-oom-prevention, etc.):api-stability,api-stability-alpha,api-stability-beta,api-stability-stable,public-api-def,developer-api-def,deprecated-api-def,whitepaper,ray-core-internal-profiling.Toctree entries are extensionless and unchanged;
.htmlredirect targets indoc/redirects/current.yamlare unaffected (HTML output paths are format-independent).Related issues
None.
Additional information
Verified the three
autofunctiontargets (PublicAPI,DeveloperAPI,Deprecatedinray.util.annotations) resolve, all 9 labels are preserved, and no bare.md→.rstlinks were introduced. Relying on the Read the Docs PR preview build for the authoritative Sphinx warning check.