[doc][DOC-933] add sphinxext-opengraph by dstrodtman · Pull Request #63343 · ray-project/ray

dstrodtman · 2026-05-14T14:10:52Z

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.

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 — 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 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 campaign: Ray docs dependency upgrades. Pattern mirrors the merged DOC-898 probe (#63197) and the obsolete-env-var removal in #63196. Strategy context: anyscale/docs:strategy/ray-docs/sphinx-rtd-viability.md "Low effort" section.

This is the bottom of a stacked series:

[doc][DOC-933] add sphinxext-opengraph #63343 — sphinxext-opengraph (this PR)
#63344 — pydata-sphinx-theme bump
#63359 — notebook language_info.name fix
#63360 — myst-nb 1.4.0 bump

DOC-933

gemini-code-assist

Code Review

This pull request integrates the sphinx-notfound-page and sphinxext-opengraph extensions into the documentation build, updating the requirements and configuration files. Feedback suggests removing the redundant ogp_site_url assignment, as it already defaults to html_baseurl. Additionally, it is recommended to use a 404.rst file instead of hardcoding the 404 page body in conf.py to improve maintainability and avoid issues with hardcoded URLs and redundant headers.

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Reviewed by Cursor Bugbot for commit b0aa77f3133fcf1431abdc9e38403782fd81503b. Configure here.}

Follow-up on the MyST xref + deplock-regen additions. Every commit on a `ray-project/ray` PR needs a `Signed-off-by:` trailer or the DCO check fails the PR. Pass `--signoff` to `git commit`, or `git commit --amend --signoff` to retro-fit. Surfaced when an early version of the DOC-932 probes (ray-project#63343, ray-project#63344) had to be force-pushed after the DCO check caught unsigned commits. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Signed-off-by: Douglas Strodtman <douglas@anyscale.com>

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:23:54Z

Force-pushed: dropped sphinx-notfound-page from this PR after its preview build surfaced a sitewide sidebar-URL regression (732/756 internal hrefs emitted with a .//en/<ver>/... prefix that doubles when the browser resolves them). Keeping sphinxext-opengraph here; the 404-page-with-absolute-URLs goal is split into a follow-up. Sorry for the re-review.

PR title and body updated to reflect the reduced scope. Downstream PRs (#63344, #63359, #63360) were rebased onto this commit.

## Why `tf-keras==2.20.0` is pinned in `doc/requirements-doc.txt` and was yanked from PyPI. The RtD build log on [#63344](#63344) surfaced the warning: ``` WARNING: The candidate selected for download or install is a yanked version: 'tf-keras' candidate (version 2.20.0 at https://files.pythonhosted.org/packages/50/9b/.../tf_keras-2.20.0-py3-none-any.whl) Reason for being yanked: <none given> ``` The warning doesn't fail the build today (`fail_on_warning: true` doesn't catch yank warnings), but a yanked version may be removed from the index in the future and break the lock. ## What Patch bump to the next non-yanked release: - `doc/requirements-doc.txt`: `tf-keras==2.20.0` → `tf-keras==2.20.1`. - `python/deplocks/docs/docbuild_depset_py3.10.lock`: update the `tf-keras` entry with the 2.20.1 wheel and sdist hashes. 2.20.1 has identical `requires_dist` to 2.20.0 (`tensorflow<2.21,>=2.20`), so the existing `tensorflow==2.20.0` pin still satisfies the constraint and no transitive deps churn. Manual lock edit per the [#63130](#63130) pattern is appropriate here. The ML / `dl-cpu-requirements.txt` / `dl-gpu-requirements.txt` pins and the `doctest_depset` lockfile also reference 2.20.0; those are out of scope for this `doc`-tagged PR and can follow up separately. ## Verification RtD PR preview build with `fail_on_warning: true`. Confirm the yanked-version warning disappears and no new warnings appear. ## Context Part of the [DOC-932](https://anyscale1.atlassian.net/browse/DOC-932) campaign: Ray docs dependency upgrades. Independent of the other open probes ([#63343](#63343), [#63344](#63344), [#63354](#63354)) — targets `master` directly. [DOC-941](https://anyscale1.atlassian.net/browse/DOC-941) Signed-off-by: Douglas Strodtman <douglas@anyscale.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

## 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 leans 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 — see pydata-sphinx-theme/pydata-sphinx-theme#759. Legacy-version 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 the template overrides under `_templates/` (`csat.html`, `extrahead.html`, `layout.html`, `navbar-anyscale.html`, and others). 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 (loses `packaging` as a direct dep, which Sphinx still pulls in transitively). ## 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 the 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 below. ## CSS fixups for theme rendering PR preview review surfaced four visual regressions on 0.17 that weren't present on 0.14 (production). All four are CSS-only — Ray's HTML and custom template are unchanged; pydata 0.14 hid or styled certain elements via theme CSS that 0.17 stopped applying or scoped differently: 1. **"Site Navigation" `<p>` visible in header.** Ray's `_templates/navbar-links.html` emits `<p class="sidebar-header-items__title">Site Navigation</p>` as a screen-reader heading. 0.14 hid it in the header via theme CSS; 0.17 doesn't. Fix: scoped `display: none` in the navbar context, preserved in the actual sidebar drawer where the heading is useful. 2. **Top-nav reference anchors underlined.** 0.14 had a broad rule removing text-decoration on `<a class="reference internal">` in the navbar; 0.17 scoped it tighter to `<a class="nav-link">`, which Ray's anchors aren't. Fix: narrower re-add of `text-decoration: none`. 3. **Library / Resources dropdown chevrons render below the link text instead of inline.** `.ref-container` is `display: flex; flex-direction: row`, but pydata 0.17 layout interactions cause `<p>` and `<i>` to wrap. Fix: `flex-wrap: nowrap` plus `flex: 0 0 auto` on the children. 4. **Top-nav items render top-aligned with the logo instead of vertically centered.** pydata 0.17 set `flex-flow: wrap` on `.navbar-header-items__center` without an explicit `align-items`, which broke the existing `height: 100%` chain on `.navbar-toplevel`. Fix: explicit `align-items: center` on `.navbar-header-items__center`. ## Validation surface The RtD PR preview build is the primary validation surface. Two layers — programmatic checks any reviewer can re-run, and manual visual checks requiring a real browser. ### Programmatic checks (re-runnable from a shell) These were run against the latest force-push and all passed: - [x] Doubled-href regression gate (root cause for [DOC-945](https://anyscale1.atlassian.net/browse/DOC-945)): `0/N` of `<a class="reference internal">` sidebar hrefs have the `.//en/<ver>/...` doubled prefix. Verified `0/755` on the latest PR preview. - [x] OpenGraph meta tags present: `og:title`, `og:type`, `og:url`, `og:description` on a sample of 5 pages. - [x] Structural diff against `/en/master`: identical `<a class="reference internal">` counts, code-block counts, cell-output counts, heading counts on 8+ sampled pages. (Compare against `/en/master`, not `/en/latest` — see DOC-943 PR #63354.) - [x] Internal-link sampling: 40/40 sidebar hrefs return 200. - [x] No `MissingIDFieldWarning`, `Notebook JSON is invalid`, `myst.xref_missing`, or `Traceback` in rendered HTML on sampled pages. - [x] Theme element presence on homepage: announcement banner, version switcher, search box, sidebar nav, theme toggle, CSAT widget, RunLLM widget, footer. ### Manual visual checks (require a real browser) A reviewer should spot-check these on the PR preview (replace `<URL>` with the RtD preview URL for this PR): 1. **Header — regression gate for the four CSS fixups.** Open `<URL>/ray-core/walkthrough.html`. Confirm: no "Site Navigation" text in the header; top-nav menu items not underlined; Library and Resources dropdown chevrons sit to the right of the link text (not below); top-nav items vertically centered with the Ray logo. 2. **Theme switcher.** Click the sun/moon/system icon top-right. Cycles through three modes (light → dark → auto). The icon visibly lags one click behind the active mode — this is the pydata 0.17 ternary-button UX issue, tracked separately for the 0.18 dropdown fix in [DOC-949](https://anyscale1.atlassian.net/browse/DOC-949). Not a blocker for this PR. 3. **Version switcher dropdown.** Click the version dropdown (next to the theme toggle). The list of versions should expand. Pick another version, confirm navigation. 4. **Sidebar TOC.** Expand and collapse a sidebar section on any narrative page. No layout shift, no broken nesting. 5. **Search.** Type `/` or `Ctrl-K`. Search input appears. Type `ray.init`. Results dropdown lists matching API entries. 6. **Mobile responsive.** Narrow the browser window below ~768px. Hamburger menu appears top-left; primary sidebar collapses into the drawer; "Site Navigation" heading is allowed to appear inside the drawer (the fix only hides it in the header). 7. **An autodoc-heavy API ref page.** Open `<URL>/ray-core/api/doc/ray.init.html`. Signature box renders, parameter table has correct columns, type cross-references are clickable. 8. **Announcement banner.** "Try Managed Ray" banner renders at top; close button works; clicking the link navigates correctly. ### Known issues parked - The pydata 0.17 theme switcher's ternary-button UX (icon visually lags click) is a known upstream issue, fixed by the dropdown in pydata 0.18 (rc1 published 2026-05-12). The bump to 0.18 depends on Sphinx 8+ ([DOC-938](https://anyscale1.atlassian.net/browse/DOC-938)). Tracked as [DOC-949](https://anyscale1.atlassian.net/browse/DOC-949). - The `preload_sidebar_nav` cache patch in `conf.py` reaches into pydata-sphinx-theme internals. If internals moved between 0.14 and 0.17, that patch will need a small follow-up. Tracked separately as [DOC-937](https://anyscale1.atlassian.net/browse/DOC-937). - `show_version_warning_banner` is a recognized config option in 0.17 but not yet enabled here. Enable is a follow-up tracked under [DOC-940](https://anyscale1.atlassian.net/browse/DOC-940). ## Stacked on #63343 This PR is stacked on top of #63343 (the additive-extensions probe). While #63343 is open, the diff in this PR shows both commits. When #63343 merges, this PR will narrow to just the pydata-sphinx-theme change. ## 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). --------- Signed-off-by: Douglas Strodtman <douglas@anyscale.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

## 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](#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 ([#63359](#63359)). ## Stack This PR is stacked on: 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) 3. [#63359](#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>

…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 `tf-keras==2.20.0` is pinned in `doc/requirements-doc.txt` and was yanked from PyPI. The RtD build log on [ray-project#63344](ray-project#63344) surfaced the warning: ``` WARNING: The candidate selected for download or install is a yanked version: 'tf-keras' candidate (version 2.20.0 at https://files.pythonhosted.org/packages/50/9b/.../tf_keras-2.20.0-py3-none-any.whl) Reason for being yanked: <none given> ``` The warning doesn't fail the build today (`fail_on_warning: true` doesn't catch yank warnings), but a yanked version may be removed from the index in the future and break the lock. ## What Patch bump to the next non-yanked release: - `doc/requirements-doc.txt`: `tf-keras==2.20.0` → `tf-keras==2.20.1`. - `python/deplocks/docs/docbuild_depset_py3.10.lock`: update the `tf-keras` entry with the 2.20.1 wheel and sdist hashes. 2.20.1 has identical `requires_dist` to 2.20.0 (`tensorflow<2.21,>=2.20`), so the existing `tensorflow==2.20.0` pin still satisfies the constraint and no transitive deps churn. Manual lock edit per the [ray-project#63130](ray-project#63130) pattern is appropriate here. The ML / `dl-cpu-requirements.txt` / `dl-gpu-requirements.txt` pins and the `doctest_depset` lockfile also reference 2.20.0; those are out of scope for this `doc`-tagged PR and can follow up separately. ## Verification RtD PR preview build with `fail_on_warning: true`. Confirm the yanked-version warning disappears and no new warnings appear. ## Context Part of the [DOC-932](https://anyscale1.atlassian.net/browse/DOC-932) campaign: Ray docs dependency upgrades. Independent of the other open probes ([ray-project#63343](ray-project#63343), [ray-project#63344](ray-project#63344), [ray-project#63354](ray-project#63354)) — targets `master` directly. [DOC-941](https://anyscale1.atlassian.net/browse/DOC-941) 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>

…#63344) ## 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 leans 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 — see pydata-sphinx-theme/pydata-sphinx-theme#759. Legacy-version 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 the template overrides under `_templates/` (`csat.html`, `extrahead.html`, `layout.html`, `navbar-anyscale.html`, and others). 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 (loses `packaging` as a direct dep, which Sphinx still pulls in transitively). ## 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 the 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 below. ## CSS fixups for theme rendering PR preview review surfaced four visual regressions on 0.17 that weren't present on 0.14 (production). All four are CSS-only — Ray's HTML and custom template are unchanged; pydata 0.14 hid or styled certain elements via theme CSS that 0.17 stopped applying or scoped differently: 1. **"Site Navigation" `<p>` visible in header.** Ray's `_templates/navbar-links.html` emits `<p class="sidebar-header-items__title">Site Navigation</p>` as a screen-reader heading. 0.14 hid it in the header via theme CSS; 0.17 doesn't. Fix: scoped `display: none` in the navbar context, preserved in the actual sidebar drawer where the heading is useful. 2. **Top-nav reference anchors underlined.** 0.14 had a broad rule removing text-decoration on `<a class="reference internal">` in the navbar; 0.17 scoped it tighter to `<a class="nav-link">`, which Ray's anchors aren't. Fix: narrower re-add of `text-decoration: none`. 3. **Library / Resources dropdown chevrons render below the link text instead of inline.** `.ref-container` is `display: flex; flex-direction: row`, but pydata 0.17 layout interactions cause `<p>` and `<i>` to wrap. Fix: `flex-wrap: nowrap` plus `flex: 0 0 auto` on the children. 4. **Top-nav items render top-aligned with the logo instead of vertically centered.** pydata 0.17 set `flex-flow: wrap` on `.navbar-header-items__center` without an explicit `align-items`, which broke the existing `height: 100%` chain on `.navbar-toplevel`. Fix: explicit `align-items: center` on `.navbar-header-items__center`. ## Validation surface The RtD PR preview build is the primary validation surface. Two layers — programmatic checks any reviewer can re-run, and manual visual checks requiring a real browser. ### Programmatic checks (re-runnable from a shell) These were run against the latest force-push and all passed: - [x] Doubled-href regression gate (root cause for [DOC-945](https://anyscale1.atlassian.net/browse/DOC-945)): `0/N` of `<a class="reference internal">` sidebar hrefs have the `.//en/<ver>/...` doubled prefix. Verified `0/755` on the latest PR preview. - [x] OpenGraph meta tags present: `og:title`, `og:type`, `og:url`, `og:description` on a sample of 5 pages. - [x] Structural diff against `/en/master`: identical `<a class="reference internal">` counts, code-block counts, cell-output counts, heading counts on 8+ sampled pages. (Compare against `/en/master`, not `/en/latest` — see DOC-943 PR ray-project#63354.) - [x] Internal-link sampling: 40/40 sidebar hrefs return 200. - [x] No `MissingIDFieldWarning`, `Notebook JSON is invalid`, `myst.xref_missing`, or `Traceback` in rendered HTML on sampled pages. - [x] Theme element presence on homepage: announcement banner, version switcher, search box, sidebar nav, theme toggle, CSAT widget, RunLLM widget, footer. ### Manual visual checks (require a real browser) A reviewer should spot-check these on the PR preview (replace `<URL>` with the RtD preview URL for this PR): 1. **Header — regression gate for the four CSS fixups.** Open `<URL>/ray-core/walkthrough.html`. Confirm: no "Site Navigation" text in the header; top-nav menu items not underlined; Library and Resources dropdown chevrons sit to the right of the link text (not below); top-nav items vertically centered with the Ray logo. 2. **Theme switcher.** Click the sun/moon/system icon top-right. Cycles through three modes (light → dark → auto). The icon visibly lags one click behind the active mode — this is the pydata 0.17 ternary-button UX issue, tracked separately for the 0.18 dropdown fix in [DOC-949](https://anyscale1.atlassian.net/browse/DOC-949). Not a blocker for this PR. 3. **Version switcher dropdown.** Click the version dropdown (next to the theme toggle). The list of versions should expand. Pick another version, confirm navigation. 4. **Sidebar TOC.** Expand and collapse a sidebar section on any narrative page. No layout shift, no broken nesting. 5. **Search.** Type `/` or `Ctrl-K`. Search input appears. Type `ray.init`. Results dropdown lists matching API entries. 6. **Mobile responsive.** Narrow the browser window below ~768px. Hamburger menu appears top-left; primary sidebar collapses into the drawer; "Site Navigation" heading is allowed to appear inside the drawer (the fix only hides it in the header). 7. **An autodoc-heavy API ref page.** Open `<URL>/ray-core/api/doc/ray.init.html`. Signature box renders, parameter table has correct columns, type cross-references are clickable. 8. **Announcement banner.** "Try Managed Ray" banner renders at top; close button works; clicking the link navigates correctly. ### Known issues parked - The pydata 0.17 theme switcher's ternary-button UX (icon visually lags click) is a known upstream issue, fixed by the dropdown in pydata 0.18 (rc1 published 2026-05-12). The bump to 0.18 depends on Sphinx 8+ ([DOC-938](https://anyscale1.atlassian.net/browse/DOC-938)). Tracked as [DOC-949](https://anyscale1.atlassian.net/browse/DOC-949). - The `preload_sidebar_nav` cache patch in `conf.py` reaches into pydata-sphinx-theme internals. If internals moved between 0.14 and 0.17, that patch will need a small follow-up. Tracked separately as [DOC-937](https://anyscale1.atlassian.net/browse/DOC-937). - `show_version_warning_banner` is a recognized config option in 0.17 but not yet enabled here. Enable is a follow-up tracked under [DOC-940](https://anyscale1.atlassian.net/browse/DOC-940). ## Stacked on ray-project#63343 This PR is stacked on top of ray-project#63343 (the additive-extensions probe). While ray-project#63343 is open, the diff in this PR shows both commits. When ray-project#63343 merges, this PR will narrow to just the pydata-sphinx-theme change. ## 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). --------- 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 a review from a team as a code owner May 14, 2026 14:10

gemini-code-assist Bot reviewed May 14, 2026

View reviewed changes

Comment thread doc/source/conf.py Outdated

Comment thread doc/source/conf.py Outdated

cursor Bot reviewed May 14, 2026

View reviewed changes

Comment thread doc/source/conf.py

dstrodtman mentioned this pull request May 14, 2026

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

Merged

6 tasks

dstrodtman force-pushed the doc-933-additive-extensions-probe branch 3 times, most recently from df18a91 to b0aa77f Compare May 14, 2026 16:32

cursor Bot reviewed May 14, 2026

View reviewed changes

Comment thread doc/source/404.md Outdated

dstrodtman force-pushed the doc-933-additive-extensions-probe branch from b0aa77f to 8156efd Compare May 14, 2026 16:50

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

elliot-barn approved these changes May 14, 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 14, 2026

dstrodtman mentioned this pull request May 15, 2026

[doc][DOC-943] add MyST xref + deplock-regen rules to doc agent context #63354

Closed

This was referenced May 15, 2026

[doc][DOC-941] unpin tf-keras: 2.20.0 was yanked #63358

Merged

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

Merged

dstrodtman force-pushed the doc-933-additive-extensions-probe branch from 8156efd to 59973f8 Compare May 15, 2026 14:13

dstrodtman changed the title ~~[doc][DOC-933] add sphinxext-opengraph and sphinx-notfound-page~~ May 15, 2026

dstrodtman mentioned this pull request May 15, 2026

[doc][DOC-942] add language_info.name to async-inference notebook #63359

Merged

dstrodtman added go add ONLY when ready to merge, run all tests and removed go add ONLY when ready to merge, run all tests labels May 15, 2026

dstrodtman mentioned this pull request May 18, 2026

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

Merged

elliot-barn approved these changes May 18, 2026

View reviewed changes

elliot-barn merged commit 075cdf4 into ray-project:master May 18, 2026
7 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

[doc][DOC-933] add sphinxext-opengraph#63343
elliot-barn merged 1 commit into
ray-project:masterfrom
dstrodtman:doc-933-additive-extensions-probe

dstrodtman commented May 14, 2026 •

edited

Loading

gemini-code-assist Bot left a comment

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment

Uh oh!

dstrodtman commented May 15, 2026

Uh oh!

Labels

2 participants

Uh oh!

Conversation

dstrodtman commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why

What

Verification

Extension diligence

What changed in the force-push

Context

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

dstrodtman commented May 15, 2026

Uh oh!

Labels

2 participants

dstrodtman commented May 14, 2026 •

edited

Loading