# PR #6871 完整报告

- 仓库：`verl-project/verl`
- 标题：[doc] fix: stop sidebar from scrolling in sync with main content
- 合并时间：2026-06-29 16:56
- 原文链接：http://prhub.com.cn/verl-project/verl/pull/6871

---

## 执行摘要

本 PR 修复了 Sphinx 文档页面中侧边栏与主内容区域同步滚动的问题。通过覆写 Sphinx RTD 主题的 `Navigation.onScroll` 方法，使侧边栏仅在鼠标悬停时滚动，提升了文档浏览体验。变更仅涉及 `docs/_static/js/resizable-sidebar.js` 文件，新增 12 行代码，无功能副作用。

## 功能与动机

根据 PR 描述，当前文档布局中，在主内容区域滚动会导致侧边栏菜单同步上下滚动，影响用户聚焦阅读。修改后，侧边栏菜单仅在用户鼠标悬停在侧边栏上时才滚动，解决了此问题。

## 实现拆解

1. **确定 Hook 点**：利用 Sphinx RTD 主题内置的 `SphinxRtdTheme.Navigation` 对象，该对象管理侧边栏的滚动同步逻辑（`onScroll` 回调在页面滚动时被调用，`onFrame` 循环根据 `winScroll` 标志更新侧边栏位置）。
2. **覆写 onScroll 方法**：在 `DOMContentLoaded` 事件中新增监听器，获取 `window.SphinxRtdTheme.Navigation` 实例，并将其 `onScroll` 方法替换为一个空操作——设置 `winScroll = false` 并记录 `winPosition`。由于 `winScroll` 为 `false`，`onFrame` 循环不会执行侧边栏位置更新，从而阻止了同步滚动。
3. **保留原有功能**：文件中原有的导航链接修复逻辑（基于 MutationObserver）保持不变，确保文档导航正常工作。

### `docs/_static/js/resizable-sidebar.js`

唯一变更文件，通过覆写 Sphinx RTD 主题的 `Navigation.onScroll` 方法禁用主内容滚动对侧边栏的影响。

```javascript
// file: docs/_static/js/resizable-sidebar.js ( 新增片段 )

// the sidebar will be scrolled when the cursor is hovered over it
document.addEventListener('DOMContentLoaded', function() {
    // 获取 Sphinx RTD 主题的 Navigation 实例
    const nav = window.SphinxRtdTheme && window.SphinxRtdTheme.Navigation;

    // 如果主题未加载，直接返回，不进行任何操作
    if (!nav) return;

    // 覆写 onScroll 方法，使其仅标记滚动状态而不触发侧边栏位置更新
    // 关键：将 winScroll 设为 false 可阻止 onFrame 循环中的侧边栏同步逻辑
    nav.onScroll = function() {
        this.winScroll = false;
        this.winPosition = this.win.scrollTop();  // 记录滚动位置（保留以备可能的外部使用）
    };
});

```

## 评论区精华

> **gemini-code-assist[bot]**(high priority): The assignment `this.winPosition = this.win.scrollTop()` is redundant and potentially unsafe. Since `winScroll` is set to `false`, the update loop never runs, making `winPosition` unused. Furthermore, calling `this.win.scrollTop()` can throw a `TypeError` if `this.win` is not yet initialized. Simplifying the function to only set `this.winScroll = false` is safer and cleaner.

该评论指出 `winPosition` 赋值多余且存在安全隐患，但 PR 合入时未修改，可能是因为保留该行对行为无影响，且开发人员认为风险可控（`this.win` 在 Navigation 实例存在时必然已初始化）。

## 风险与影响

- **低风险**：变更仅限前端 JS，不涉及核心分布式训练 / 推理逻辑。
- 潜在风险：若 Sphinx RTD 主题未来版本更改内部 API（如移除 `onScroll` 或改变 `winScroll` 语义），此 hack 可能失效。
- 影响范围：仅影响 Sphinx 构建的 Read the Docs 风格文档页面，所有查看文档的用户都将受益。

## 关联脉络

无直接关联的 PR 或 Issue。