执行摘要
本 PR 修复了 Sphinx 文档页面中侧边栏与主内容区域同步滚动的问题。通过覆写 Sphinx RTD 主题的 Navigation.onScroll 方法，使侧边栏仅在鼠标悬停时滚动，提升了文档浏览体验。变更仅涉及 docs/_static/js/resizable-sidebar.js 文件，新增 12 行代码，无功能副作用。
功能与动机
根据 PR 描述，当前文档布局中，在主内容区域滚动会导致侧边栏菜单同步上下滚动，影响用户聚焦阅读。修改后，侧边栏菜单仅在用户鼠标悬停在侧边栏上时才滚动，解决了此问题。
实现拆解
- 确定 Hook 点：利用 Sphinx RTD 主题内置的
SphinxRtdTheme.Navigation 对象，该对象管理侧边栏的滚动同步逻辑（onScroll 回调在页面滚动时被调用，onFrame 循环根据 winScroll 标志更新侧边栏位置）。
- 覆写 onScroll 方法：在
DOMContentLoaded 事件中新增监听器，获取 window.SphinxRtdTheme.Navigation 实例，并将其 onScroll 方法替换为一个空操作——设置 winScroll = false 并记录 winPosition。由于 winScroll 为 false，onFrame 循环不会执行侧边栏位置更新，从而阻止了同步滚动。
- 保留原有功能：文件中原有的导航链接修复逻辑（基于 MutationObserver）保持不变，确保文档导航正常工作。
docs/_static/js/resizable-sidebar.js
唯一变更文件，通过覆写 Sphinx RTD 主题的 Navigation.onScroll 方法禁用主内容滚动对侧边栏的影响。
// 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。
参与讨论