[doc][DOC-935] bump myst-nb 1.0.0rc0 -> 1.4.0 by dstrodtman · Pull Request #63360 · ray-project/ray

dstrodtman · 2026-05-15T04:18:49Z

Why

myst-nb is pinned at 1.0.0rc0 (a release candidate) in doc/requirements-doc.txt. Latest stable is 1.4.0 — four minor releases ahead. The # Pin when new release is made comment is stale: 1.0.0 shipped, and the project has moved on.

Notebook parsing/output is downstream of myst-nb. Ray ships 127 Jupyter notebooks (RUN_NOTEBOOKS=off by default), parsed from stored cell outputs. The bump tests the parsing path against existing outputs without requiring re-execution.

What

doc/requirements-doc.txt: myst-nb==1.0.0rc0 → myst-nb==1.4.0. Drops the stale "pin when new release is made" comment.
python/deplocks/docs/docbuild_depset_py3.10.lock: update version + hashes for myst-nb.

Lock-file scope

myst-nb 1.4.0 declares more core dependencies than 1.0.0rc0 — ipython, ipykernel, nbclient, pyyaml, typing-extensions, importlib-metadata, and sphinx>=5. I verified that all of these are already present in docbuild_depset_py3.10.lock as transitives from other packages, so the hand-edit per the #63130 pattern works here without regenerating the full lock.

The lock's # via comments for those transitives don't yet include myst-nb as a source. Those comments are informational (they don't affect resolution), but raydepsets --check in CI will flag them if it cares about the discrepancy. If CI complains, the fix is either to update via-comments by hand or regenerate via:

bazelisk run //ci/raydepsets:raydepsets -- build ci/raydepsets/configs/docs.depsets.yaml

Validation surface

RtD PR preview build with fail_on_warning: true. Build must succeed.
Spot check a notebook-rendered page (e.g., Tune tutorials, RLlib examples).
Look for new warnings in build logs.

Risks

1.0 → 1.4 may have changed default output rendering for some MIME types. The nb_mime_priority_overrides and nb_execution_mode = "off" settings in conf.py should still apply but warrant a visual check.
Migrations between rc and stable can be sensitive on edge cases.
The cell-id MissingIDFieldWarning (DOC-944) may escalate to a hard error under stricter validation in 1.4.0. The strict language_info.name error is fixed below in the stack (#63359).

Stack

This PR is stacked on:

#63343 — DOC-933 (additive extensions)
#63344 — DOC-934 (pydata-sphinx-theme bump)
#63359 — DOC-942 (notebook language_info.name fix)

Base is master per the team's fork-stack convention; the diff temporarily includes the lower PRs and shrinks as they merge. The CI signal for this PR validates the combined state of the four changes.

Context

Part of the DOC-932 campaign: Ray docs dependency upgrades. Strategy context: anyscale/docs:strategy/ray-docs/sphinx-rtd-viability.md and config-deep-dive.md.

DOC-935

gemini-code-assist

Code Review

This pull request updates documentation dependencies and configurations. Key changes include upgrading pydata-sphinx-theme to 0.17.1 and myst-nb to 1.4.0, adding sphinx-notfound-page and sphinxext-opengraph extensions, and creating a custom 404 page. Additionally, it corrects Pygments style keys in conf.py and adds required metadata to a Jupyter notebook for compatibility. I have no feedback to provide.

Add `sphinxext-opengraph` to the docs build for per-page Open Graph metadata. `ogp_site_url = html_baseurl` keeps the `og:url` tag aligned with Sphinx's `<link rel="canonical">` so the canonical URL tracks one source of truth instead of falling back to RtD's `READTHEDOCS_CANONICAL_URL` (which can diverge from `html_baseurl`). Originally bundled `sphinx-notfound-page` alongside but dropped it: the extension's `html-page-context` override prepends a `/en/<version>/` URL prefix to all internal links on every page, not just the 404 page, which broke sidebar navigation on RtD PR preview builds (732/756 `<a class="reference internal">` hrefs had the doubled-prefix pattern `.//en/<ver>/...`). The 404-page-with-absolute-URLs goal is tracked separately so it can be re-attempted with a config or extension that doesn't break sitewide navigation. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Signed-off-by: Douglas Strodtman <douglas@anyscale.com>

dstrodtman · 2026-05-15T14:24:18Z

Rebased onto the updated #63359. DOC-935 content is unchanged. The full stack now reads: #63343 (sphinxext-opengraph only — sphinx-notfound-page dropped) → #63344 (pydata theme) → #63359 (notebook language_info.name) → #63360 (this PR — myst-nb 1.4.0).

dstrodtman · 2026-05-15T19:34:09Z

Rebased again onto the amended #63359 (which itself rebased onto the amended #63344 with two pydata 0.17 CSS fixes). DOC-935 content is unchanged. Stack now: master ← #63343 ← #63344 (+CSS fixes) ← #63359 ← #63360 (this PR).

## Why pydata-sphinx-theme is pinned at 0.14.1 (April 2023). Latest is 0.17.1 (March 2026). Two reasons to take this bump now: 1. The Anyscale docs team's legacy-versions assessment relies on the theme's `show_version_warning_banner` option to add an EOS banner to `releases-X.Y.Z/` builds. That option doesn't exist in 0.14.1 — the pydata-sphinx-theme/pydata-sphinx-theme#759 feature request was filed against later versions. Banner work blocks on this bump. 2. Theme integration is the highest-signal validation surface for a Ray docs theme bump anyway: custom navbar, "Try Managed Ray" announcement banner, version-switcher with `switcher.json_url` pointing at the generated `versions.json`, and template overrides under `_templates/` (`csat.html`, `extrahead.html`, `layout.html`, `navbar-anyscale.html`, etc.). Compatibility: 0.17.1 declares `sphinx<10,>=7.0`, which is compatible with the current Sphinx 7.3.7 pin. Runtime deps are otherwise unchanged (lose `packaging` as a direct dep — still pulled in transitively from Sphinx). ## What Four files changed: - `doc/requirements-doc.txt`: `pydata-sphinx-theme==0.14.1` -> `pydata-sphinx-theme==0.17.1`. - `python/deplocks/docs/docbuild_depset_py3.10.lock`: bump pydata-sphinx-theme version pin and hashes. No transitive-dep changes; the runtime deps in 0.17.1 are a strict subset (lost `packaging` direct pin, which Sphinx still pulls in). - `doc/source/conf.py`: rename `pygment_light_style` and `pygment_dark_style` to `pygments_light_style` and `pygments_dark_style` (added `s`). The theme renamed these in 0.15.3 and the old names emit deprecation warnings, which would fail the build under `fail_on_warning: true`. - `doc/source/_static/css/custom.css`: four follow-on CSS rules to compensate for theme-CSS changes between 0.14 and 0.17. See "CSS fixups for theme rendering" below. ## CSS fixups for theme rendering PR preview builds surfaced four visual regressions on 0.17 that aren't present on production (0.14): 1. The `<p class="sidebar-header-items__title">Site Navigation</p>` that Ray's `_templates/navbar-links.html` emits is no longer hidden in the header context (it's still useful as a screen-reader heading inside the sidebar drawer). The CSS rule from 0.14 that hid it stopped applying. Added a narrowly-scoped hide rule that preserves it in the sidebar. 2. Top-nav reference anchors (`<a class="reference internal">`) now render underlined. pydata 0.14 had a broad rule removing text-decoration on these in the navbar; 0.17 scoped it tighter so it only matches `<a class="nav-link">`, which our anchors aren't. Added a narrower re-add of `text-decoration: none`. 3. Top-nav text renders top-aligned with the logo and the dropdown chevrons on Library / Resources appear below the link text instead of inline. Both symptoms have a single cause: pydata 0.14's `.navbar-nav li a { height: 100% }` rule was scoped to `ul.navbar-nav li a` in 0.17, so it stopped matching the `<a>` inside Ray's `<nav class="navbar-nav">`. Without `height: 100%`, the `<a>` shrinks to text height (~26px) inside its 64px-tall `<p>` parent, leaving the text top-aligned and the chevron (centered on the 64px `.ref-container`) visually below the misaligned text. Restored `height: 100%` on `<a>` so the existing `justify-content: center` can vertically center the text in the full-height anchor. 4. The "Try Ray with $100 credit" announcement banner renders in pydata's default lavender (`var(--pst-color-secondary-bg)`) instead of Ray's teal. pydata 0.14 painted the announcement background via an absolutely-positioned `::after` pseudo-element. 0.17 dropped the pseudo-element and now sets `background-color` directly on `.bd-header-announcement`, so Ray's `::after`-targeted teal override silently became a no-op. Moved the teal `background-color` onto `.bd-header-announcement` itself. The fixes are scoped narrowly to the navbar / banner containers so they don't affect the sidebar drawer or other places where these elements still need their default rendering. An additional regression — the theme switcher icon visually lagging one click behind the active mode — is the pydata-sphinx-theme/pydata-sphinx-theme#1941 ternary-button UX issue, which is fixed by the dropdown landing in 0.18 (rc1 released 2026-05-12). Out of scope for this PR. ## Validation surface After this lands and the RtD PR preview build is green: - Visual check on a representative landing page: navbar renders, logo loads, version-switcher dropdown is populated, announcement banner renders in Ray's teal, the close button works. "Site Navigation" string does NOT appear in the header. Top-nav menu items do NOT render underlined. Library / Resources dropdown chevrons render inline with their text. Top-nav items vertically center with the logo. - Visual check of an autodoc-heavy API ref page: signature rendering, inheritance, parameter table styling. - Visual check of the sidebar TOC behavior — Ray patches `preload_sidebar_nav` against pydata-sphinx-theme's internal cache. This is the highest-risk piece (theme internals can shift between minors). Filed as a separate de-monkeypatch task; for now we accept the risk of needing a small follow-up if internals moved. - Confirm `show_version_warning_banner` is now a recognized config option (smoke test in a follow-up PR; not enabled in this one). - No new warnings in the RtD build log (`fail_on_warning: true`). ## Context Part of the [DOC-932](https://anyscale1.atlassian.net/browse/DOC-932) campaign: Ray docs dependency upgrades. Strategy context in `anyscale/docs:strategy/ray-docs/config-deep-dive.md` section 1.2 and `sphinx-rtd-viability.md`. Unblocks [DOC-940](https://anyscale1.atlassian.net/browse/DOC-940) (`show_version_warning_banner` enable on legacy version archives). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Signed-off-by: Douglas Strodtman <douglas@anyscale.com>

doc/source/serve/tutorials/asynchronous-inference/content/asynchronous-inference.ipynb had metadata.language_info = {"pygments_lexer": "ipython3"}, missing the nbformat-required "name" field. nbformat validation logs this as an error during the RtD build (surfaced on ray-project#63344). Adds "name": "python" to match the existing kernelspec (language: python). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Signed-off-by: Douglas Strodtman <douglas@anyscale.com>

myst-nb was pinned at the 1.0.0rc0 release candidate. Bump to 1.4.0 (current stable, four minor releases ahead). myst-nb 1.4.0 lists more core deps than 1.0.0rc0 (ipython, ipykernel, nbclient, pyyaml, typing-extensions, importlib-metadata, sphinx>=5), but all of those are already present in the docbuild lockfile as transitives, so the lock edit is just a version + hash bump. Drops the stale "pin when new release is made" comment. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Signed-off-by: Douglas Strodtman <douglas@anyscale.com>

pydata-sphinx-theme 0.17 replaced the toctree's <input class="toctree-checkbox"> toggle with HTML5 <details>/<summary>. preload_sidebar_nav walks the active page's ancestor <li class="has-children"> and previously checked the <input>; with 0.17 there is no <input>, so no <details> ever gets `open` and the sidebar starts fully collapsed on every page. Open the <details> when present and keep the <input> branch as a fallback for 0.14. Behavior is unchanged on master (which is still pinned at 0.14.1). Stacked on ray-project#63360 (DOC-935 myst-nb bump) on top of the DOC-934 pydata-theme bump where the regression was introduced. DOC-937 (de-monkeypatch preload_sidebar_nav) remains the proper follow-up rework. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Signed-off-by: Douglas Strodtman <douglas@anyscale.com>

## Why Add `sphinxext-opengraph` — per-page Open Graph metadata. `ogp_site_url` is pinned to `html_baseurl` so the `og:url` tag stays aligned with Sphinx's `<link rel="canonical">`. Improves rich-link previews when docs pages get shared and tightens SEO signal. Low-effort additive change called out as a Bucket 1 quick win in the Anyscale docs team's agent-friendliness assessment. ## What - `doc/requirements-doc.txt`: add `sphinxext-opengraph==0.13.0`. - `doc/source/conf.py`: append `"sphinxext.opengraph"` to `extensions`; set `ogp_site_url = html_baseurl`. - `python/deplocks/docs/docbuild_depset_py3.10.lock`: package entry plus via-comment addition on `sphinx` (the only runtime dep, already pinned, so no further transitives). Matches the manual-lock-edit pattern used in [#63130](#63130). ## Verification After this lands and `latest` rebuilds: - A representative doc page's `<head>` includes `<meta property="og:*">` tags reflecting page title, description, and the site URL. - No new warnings in the RtD build log (`fail_on_warning: true`). ## Extension diligence [`sphinxext-opengraph`](https://github.com/sphinx-doc/sphinxext-opengraph) — official `sphinx-doc` org project, BSD-2-Clause. Latest release 0.13.0 (March 2026). Pure-Python, depends only on Sphinx (already pinned to 7.3.7), no system-level requirements. ## What changed in the force-push This PR originally also bundled [`sphinx-notfound-page`](https://github.com/readthedocs/sphinx-notfound-page) to give the Ray docs a 404 page with absolute URLs. Dropped on 2026-05-15 because the RtD PR preview build surfaced a sitewide regression: 732 of 756 `<a class="reference internal">` sidebar hrefs were emitted with a `.//en/<ver>/...` prefix that doubles when the browser resolves them against the build's `/en/<ver>/` deploy path. Production docs.ray.io (which doesn't have the extension) was unaffected (0/747 hrefs). The cause is sphinx-notfound-page's `html-page-context` hook: it overrides `pathto`/`toctree` for **every** page in the build, prepending a URL prefix derived from `READTHEDOCS_CANONICAL_URL`. The extension docs imply this is "for the 404 page only," but the override fires on every page-context event. On a PR preview where the canonical URL differs from `html_baseurl`, this produces the doubled-prefix anti-pattern across the entire sidebar. The 404-page-with-absolute-URLs goal is tracked separately so it can be re-attempted with a config or extension that doesn't break sitewide navigation. Options to revisit: `notfound_urls_prefix = None`, a custom 404 template that bypasses the global `pathto` override, or `html_extra_path` with a static 404. ## Context Part of the [DOC-932](https://anyscale1.atlassian.net/browse/DOC-932) campaign: Ray docs dependency upgrades. Pattern mirrors the merged [DOC-898](https://anyscale1.atlassian.net/browse/DOC-898) probe ([#63197](#63197)) and the obsolete-env-var removal in [#63196](#63196). Strategy context: `anyscale/docs:strategy/ray-docs/sphinx-rtd-viability.md` "Low effort" section. This is the bottom of a stacked series: 1. **#63343 — sphinxext-opengraph (this PR)** 2. [#63344](#63344) — pydata-sphinx-theme bump 3. [#63359](#63359) — notebook `language_info.name` fix 4. [#63360](#63360) — myst-nb 1.4.0 bump [DOC-933](https://anyscale1.atlassian.net/browse/DOC-933) Signed-off-by: Douglas Strodtman <douglas@anyscale.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…17 (#63455) ## Why pydata-sphinx-theme 0.17 replaced the toctree's `<input class="toctree-checkbox">` + `<label>` collapse/expand toggle with HTML5 `<details><summary>`. [DOC-934](https://anyscale1.atlassian.net/browse/DOC-934) ([#63344](#63344)) bumped the theme 0.14.1 → 0.17.1 and surfaced a regression in Ray's `preload_sidebar_nav` monkey-patch in `doc/source/custom_directives.py`. The active-page loop walks `<a class="reference internal">`'s ancestor LIs and previously did `parent_li.find("input")` plus `el.attrs["checked"] = True`. With 0.17 there's no `<input>` to find — `find` returns `None`, the `if el:` branch never fires, and **no `<details>` ever gets `open` on any page**. The sidebar starts fully collapsed and the user's current location is never revealed. Confirmed on the RtD preview for [#63360](#63360) (top of the DOC-932 stack): page HTML has 84 `<details>` elements, zero with `open`; master (still pinned at 0.14.1) renders the same page with 86 `<input>` checkboxes, two of them `checked="checked"` (the current page and its toctree-l1 ancestor). This regression was anticipated in DOC-934's Risks section. ## What In `preload_sidebar_nav`, prefer `<details open>` when present and keep the `<input checked>` branch as a fallback so the code stays correct under either theme version: ```python for parent_li in a.find_parents("li", attrs={"class": "has-children"}): details = parent_li.find("details", recursive=False) if details is not None: details.attrs["open"] = "" continue el = parent_li.find("input") if el: el.attrs["checked"] = True ``` Single-file change, no behavioral change against pydata 0.14. ## Stack Stacked on top of (in order from base to tip): 1. [#63343](#63343) — [DOC-933](https://anyscale1.atlassian.net/browse/DOC-933) additive extensions 2. [#63344](#63344) — [DOC-934](https://anyscale1.atlassian.net/browse/DOC-934) pydata-sphinx-theme bump (the regression source) 3. [#63359](#63359) — [DOC-942](https://anyscale1.atlassian.net/browse/DOC-942) notebook `language_info.name` fix 4. [#63360](#63360) — [DOC-935](https://anyscale1.atlassian.net/browse/DOC-935) myst-nb bump Base is `master` per the fork-stack convention; the diff temporarily includes the lower PRs and shrinks as they merge. This PR cannot ship before #63344 is approved. ## Relationship to DOC-937 [DOC-937](https://anyscale1.atlassian.net/browse/DOC-937) (de-monkeypatch `custom_directives.py`) is the proper follow-up: rework `preload_sidebar_nav` as a theme-template override or Sphinx event hook rather than reaching into theme internals. That work is still scoped before the [DOC-938](https://anyscale1.atlassian.net/browse/DOC-938) Sphinx 7→8 probe. This PR keeps the monkey-patch alive a bit longer so the theme bump can land first. ## Validation surface - RtD PR preview build with `fail_on_warning: true`. - Visual check on `rllib/user-guides.html` (the page where the regression was first observed): User Guides section auto-expanded with current-page styling, ancestor chain (Ray RLlib > User Guides) open. - Spot-check pages at different depths (toctree-l1 leaf, toctree-l3 leaf, toctree-l4 leaf). - Confirm manual chevron clicks still expand/collapse other sections normally. [DOC-1044](https://anyscale1.atlassian.net/browse/DOC-1044) --------- Signed-off-by: Douglas Strodtman <douglas@anyscale.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Co-authored-by: Elliot Barnwell <elliot.barnwell@anyscale.com>

## Why Add `sphinxext-opengraph` — per-page Open Graph metadata. `ogp_site_url` is pinned to `html_baseurl` so the `og:url` tag stays aligned with Sphinx's `<link rel="canonical">`. Improves rich-link previews when docs pages get shared and tightens SEO signal. Low-effort additive change called out as a Bucket 1 quick win in the Anyscale docs team's agent-friendliness assessment. ## What - `doc/requirements-doc.txt`: add `sphinxext-opengraph==0.13.0`. - `doc/source/conf.py`: append `"sphinxext.opengraph"` to `extensions`; set `ogp_site_url = html_baseurl`. - `python/deplocks/docs/docbuild_depset_py3.10.lock`: package entry plus via-comment addition on `sphinx` (the only runtime dep, already pinned, so no further transitives). Matches the manual-lock-edit pattern used in [ray-project#63130](ray-project#63130). ## Verification After this lands and `latest` rebuilds: - A representative doc page's `<head>` includes `<meta property="og:*">` tags reflecting page title, description, and the site URL. - No new warnings in the RtD build log (`fail_on_warning: true`). ## Extension diligence [`sphinxext-opengraph`](https://github.com/sphinx-doc/sphinxext-opengraph) — official `sphinx-doc` org project, BSD-2-Clause. Latest release 0.13.0 (March 2026). Pure-Python, depends only on Sphinx (already pinned to 7.3.7), no system-level requirements. ## What changed in the force-push This PR originally also bundled [`sphinx-notfound-page`](https://github.com/readthedocs/sphinx-notfound-page) to give the Ray docs a 404 page with absolute URLs. Dropped on 2026-05-15 because the RtD PR preview build surfaced a sitewide regression: 732 of 756 `<a class="reference internal">` sidebar hrefs were emitted with a `.//en/<ver>/...` prefix that doubles when the browser resolves them against the build's `/en/<ver>/` deploy path. Production docs.ray.io (which doesn't have the extension) was unaffected (0/747 hrefs). The cause is sphinx-notfound-page's `html-page-context` hook: it overrides `pathto`/`toctree` for **every** page in the build, prepending a URL prefix derived from `READTHEDOCS_CANONICAL_URL`. The extension docs imply this is "for the 404 page only," but the override fires on every page-context event. On a PR preview where the canonical URL differs from `html_baseurl`, this produces the doubled-prefix anti-pattern across the entire sidebar. The 404-page-with-absolute-URLs goal is tracked separately so it can be re-attempted with a config or extension that doesn't break sitewide navigation. Options to revisit: `notfound_urls_prefix = None`, a custom 404 template that bypasses the global `pathto` override, or `html_extra_path` with a static 404. ## Context Part of the [DOC-932](https://anyscale1.atlassian.net/browse/DOC-932) campaign: Ray docs dependency upgrades. Pattern mirrors the merged [DOC-898](https://anyscale1.atlassian.net/browse/DOC-898) probe ([ray-project#63197](ray-project#63197)) and the obsolete-env-var removal in [ray-project#63196](ray-project#63196). Strategy context: `anyscale/docs:strategy/ray-docs/sphinx-rtd-viability.md` "Low effort" section. This is the bottom of a stacked series: 1. **ray-project#63343 — sphinxext-opengraph (this PR)** 2. [ray-project#63344](ray-project#63344) — pydata-sphinx-theme bump 3. [ray-project#63359](ray-project#63359) — notebook `language_info.name` fix 4. [ray-project#63360](ray-project#63360) — myst-nb 1.4.0 bump [DOC-933](https://anyscale1.atlassian.net/browse/DOC-933) Signed-off-by: Douglas Strodtman <douglas@anyscale.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Signed-off-by: phattruong <23120318@student.hcmus.edu.vn>

## Why `myst-nb` is pinned at `1.0.0rc0` (a release candidate) in `doc/requirements-doc.txt`. Latest stable is `1.4.0` — four minor releases ahead. The `# Pin when new release is made` comment is stale: 1.0.0 shipped, and the project has moved on. Notebook parsing/output is downstream of `myst-nb`. Ray ships 127 Jupyter notebooks (`RUN_NOTEBOOKS=off` by default), parsed from stored cell outputs. The bump tests the parsing path against existing outputs without requiring re-execution. ## What - `doc/requirements-doc.txt`: `myst-nb==1.0.0rc0` → `myst-nb==1.4.0`. Drops the stale "pin when new release is made" comment. - `python/deplocks/docs/docbuild_depset_py3.10.lock`: update version + hashes for `myst-nb`. ## Lock-file scope myst-nb 1.4.0 declares more core dependencies than 1.0.0rc0 — `ipython`, `ipykernel`, `nbclient`, `pyyaml`, `typing-extensions`, `importlib-metadata`, and `sphinx>=5`. I verified that **all** of these are already present in `docbuild_depset_py3.10.lock` as transitives from other packages, so the hand-edit per the [ray-project#63130](ray-project#63130) pattern works here without regenerating the full lock. The lock's `# via` comments for those transitives don't yet include `myst-nb` as a source. Those comments are informational (they don't affect resolution), but `raydepsets --check` in CI will flag them if it cares about the discrepancy. If CI complains, the fix is either to update via-comments by hand or regenerate via: ```bash bazelisk run //ci/raydepsets:raydepsets -- build ci/raydepsets/configs/docs.depsets.yaml ``` ## Validation surface - RtD PR preview build with `fail_on_warning: true`. Build must succeed. - Spot check a notebook-rendered page (e.g., Tune tutorials, RLlib examples). - Look for new warnings in build logs. ## Risks - 1.0 → 1.4 may have changed default output rendering for some MIME types. The `nb_mime_priority_overrides` and `nb_execution_mode = "off"` settings in `conf.py` should still apply but warrant a visual check. - Migrations between rc and stable can be sensitive on edge cases. - The cell-id `MissingIDFieldWarning` ([DOC-944](https://anyscale1.atlassian.net/browse/DOC-944)) may escalate to a hard error under stricter validation in 1.4.0. The strict `language_info.name` error is fixed below in the stack ([ray-project#63359](ray-project#63359)). ## Stack This PR is stacked on: 1. [ray-project#63343](ray-project#63343) — [DOC-933](https://anyscale1.atlassian.net/browse/DOC-933) (additive extensions) 2. [ray-project#63344](ray-project#63344) — [DOC-934](https://anyscale1.atlassian.net/browse/DOC-934) (pydata-sphinx-theme bump) 3. [ray-project#63359](ray-project#63359) — [DOC-942](https://anyscale1.atlassian.net/browse/DOC-942) (notebook `language_info.name` fix) Base is `master` per the team's fork-stack convention; the diff temporarily includes the lower PRs and shrinks as they merge. The CI signal for this PR validates the combined state of the four changes. ## Context Part of the [DOC-932](https://anyscale1.atlassian.net/browse/DOC-932) campaign: Ray docs dependency upgrades. Strategy context: `anyscale/docs:strategy/ray-docs/sphinx-rtd-viability.md` and `config-deep-dive.md`. [DOC-935](https://anyscale1.atlassian.net/browse/DOC-935) --------- Signed-off-by: Douglas Strodtman <douglas@anyscale.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Signed-off-by: phattruong <23120318@student.hcmus.edu.vn>

…17 (ray-project#63455) ## Why pydata-sphinx-theme 0.17 replaced the toctree's `<input class="toctree-checkbox">` + `<label>` collapse/expand toggle with HTML5 `<details><summary>`. [DOC-934](https://anyscale1.atlassian.net/browse/DOC-934) ([ray-project#63344](ray-project#63344)) bumped the theme 0.14.1 → 0.17.1 and surfaced a regression in Ray's `preload_sidebar_nav` monkey-patch in `doc/source/custom_directives.py`. The active-page loop walks `<a class="reference internal">`'s ancestor LIs and previously did `parent_li.find("input")` plus `el.attrs["checked"] = True`. With 0.17 there's no `<input>` to find — `find` returns `None`, the `if el:` branch never fires, and **no `<details>` ever gets `open` on any page**. The sidebar starts fully collapsed and the user's current location is never revealed. Confirmed on the RtD preview for [ray-project#63360](ray-project#63360) (top of the DOC-932 stack): page HTML has 84 `<details>` elements, zero with `open`; master (still pinned at 0.14.1) renders the same page with 86 `<input>` checkboxes, two of them `checked="checked"` (the current page and its toctree-l1 ancestor). This regression was anticipated in DOC-934's Risks section. ## What In `preload_sidebar_nav`, prefer `<details open>` when present and keep the `<input checked>` branch as a fallback so the code stays correct under either theme version: ```python for parent_li in a.find_parents("li", attrs={"class": "has-children"}): details = parent_li.find("details", recursive=False) if details is not None: details.attrs["open"] = "" continue el = parent_li.find("input") if el: el.attrs["checked"] = True ``` Single-file change, no behavioral change against pydata 0.14. ## Stack Stacked on top of (in order from base to tip): 1. [ray-project#63343](ray-project#63343) — [DOC-933](https://anyscale1.atlassian.net/browse/DOC-933) additive extensions 2. [ray-project#63344](ray-project#63344) — [DOC-934](https://anyscale1.atlassian.net/browse/DOC-934) pydata-sphinx-theme bump (the regression source) 3. [ray-project#63359](ray-project#63359) — [DOC-942](https://anyscale1.atlassian.net/browse/DOC-942) notebook `language_info.name` fix 4. [ray-project#63360](ray-project#63360) — [DOC-935](https://anyscale1.atlassian.net/browse/DOC-935) myst-nb bump Base is `master` per the fork-stack convention; the diff temporarily includes the lower PRs and shrinks as they merge. This PR cannot ship before ray-project#63344 is approved. ## Relationship to DOC-937 [DOC-937](https://anyscale1.atlassian.net/browse/DOC-937) (de-monkeypatch `custom_directives.py`) is the proper follow-up: rework `preload_sidebar_nav` as a theme-template override or Sphinx event hook rather than reaching into theme internals. That work is still scoped before the [DOC-938](https://anyscale1.atlassian.net/browse/DOC-938) Sphinx 7→8 probe. This PR keeps the monkey-patch alive a bit longer so the theme bump can land first. ## Validation surface - RtD PR preview build with `fail_on_warning: true`. - Visual check on `rllib/user-guides.html` (the page where the regression was first observed): User Guides section auto-expanded with current-page styling, ancestor chain (Ray RLlib > User Guides) open. - Spot-check pages at different depths (toctree-l1 leaf, toctree-l3 leaf, toctree-l4 leaf). - Confirm manual chevron clicks still expand/collapse other sections normally. [DOC-1044](https://anyscale1.atlassian.net/browse/DOC-1044) --------- Signed-off-by: Douglas Strodtman <douglas@anyscale.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Co-authored-by: Elliot Barnwell <elliot.barnwell@anyscale.com> Signed-off-by: phattruong <23120318@student.hcmus.edu.vn>

dstrodtman requested review from a team as code owners May 15, 2026 04:18

gemini-code-assist Bot reviewed May 15, 2026

View reviewed changes

ray-gardener Bot added docs An issue or change related to documentation core Issues that should be addressed in Ray Core labels May 15, 2026

dstrodtman added the go add ONLY when ready to merge, run all tests label May 15, 2026

dstrodtman force-pushed the doc-935-myst-nb-bump branch from 6292715 to 5dd0ce2 Compare May 15, 2026 14:16

dstrodtman mentioned this pull request May 15, 2026

[doc][DOC-933] add sphinxext-opengraph #63343

Merged

dstrodtman force-pushed the doc-935-myst-nb-bump branch from 5dd0ce2 to 81d09fd Compare May 15, 2026 19:33

dstrodtman mentioned this pull request May 15, 2026

[doc][DOC-934] bump pydata-sphinx-theme 0.14.1 -> 0.17.1 #63344

Merged

6 tasks

dstrodtman force-pushed the doc-935-myst-nb-bump branch 2 times, most recently from e67008e to a74b73c Compare May 18, 2026 11:55

dstrodtman mentioned this pull request May 18, 2026

[doc][DOC-1044] restore active-page sidebar expansion under pydata 0.17 #63455

Merged

dstrodtman and others added 3 commits May 18, 2026 14:14

dstrodtman force-pushed the doc-935-myst-nb-bump branch from a74b73c to 71b3ac2 Compare May 18, 2026 18:17

elliot-barn approved these changes May 19, 2026

View reviewed changes

elliot-barn merged commit a746498 into ray-project:master May 19, 2026
6 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[doc][DOC-935] bump myst-nb 1.0.0rc0 -> 1.4.0#63360

[doc][DOC-935] bump myst-nb 1.0.0rc0 -> 1.4.0#63360
elliot-barn merged 4 commits into
ray-project:masterfrom
dstrodtman:doc-935-myst-nb-bump

dstrodtman commented May 15, 2026

gemini-code-assist Bot left a comment

dstrodtman commented May 15, 2026

dstrodtman commented May 15, 2026

Uh oh!

Labels

2 participants

Uh oh!

Conversation

dstrodtman commented May 15, 2026

Why

What

Lock-file scope

Validation surface

Risks

Stack

Context

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

dstrodtman commented May 15, 2026

dstrodtman commented May 15, 2026

Uh oh!

Labels

2 participants