Sphinx RST层级文档结构下，如何在HTML输出中展开子页面？

我之前做项目时刚好碰到过一模一样的需求，结合自己的实践和踩过的坑，给你分享几个可行的方法：

1. 利用主题自带配置（最简单，优先尝试） #

大部分主流Sphinx主题（比如Read the Docs、Alabaster）都自带导航展开的配置项，直接在conf.py里修改即可：

针对Read the Docs主题（sphinx_rtd_theme） #

在conf.py中添加或修改如下配置：

html_theme = 'sphinx_rtd_theme'
html_theme_options = {
    # 设为False会展开所有导航项，设为True则只展开当前页面所在分支
    'collapse_navigation': False,
    # 控制导航显示的深度，根据你的章节层级调整（比如3或4）
    'navigation_depth': 3,
    # 可选：让导航栏固定在页面顶部
    'sticky_navigation': True
}

如果只希望当前页面所在的子分支自动展开，而不是全部导航都展开，把collapse_navigation设为True即可，主题会自动识别当前页面位置并展开对应层级的导航。

针对Alabaster主题 #

如果用的是Alabaster，配置类似：

html_theme = 'alabaster'
html_theme_options = {
    # False=展开所有导航，True=仅展开当前分支
    'globaltoc_collapse': False,
    'globaltoc_depth': 3
}

2. 自定义JavaScript实现精准控制（适合特殊需求） #

如果自带配置满足不了你的要求（比如想要更灵活的展开逻辑），可以添加自定义JS来控制侧边栏导航的展开状态：

1. 在你的Sphinx项目根目录下创建_static/js文件夹，新建一个expand_nav.js文件，内容如下：

document.addEventListener('DOMContentLoaded', function() {
    // 获取所有导航里的子菜单
    const subMenus = document.querySelectorAll('.toctree-l2, .toctree-l3');
    // 获取当前页面对应的导航项
    const currentItem = document.querySelector('.current');
    
    // 展开当前页面所在的所有父级菜单
    let parent = currentItem.parentElement;
    while (parent && parent.classList.contains('toctree-wrapper')) {
        parent.style.display = 'block';
        parent = parent.parentElement;
    }
    
    // 可选：展开所有子菜单（如果需要全部展开）
    // subMenus.forEach(menu => menu.style.display = 'block');
});

2. 在conf.py中添加这个JS文件的引用：

html_js_files = [
    'js/expand_nav.js',
]

这样页面加载时会自动展开当前页面所在的所有层级导航。

3. 检查toctree配置确保层级正确 #

最后要确保你的toctree配置没有限制深度，比如根目录的index.rst里的toctree：

.. toctree::
    :maxdepth: 3  # 要大于等于你的章节层级
    :caption: 目录

    chapter1/index
    chapter2/index
    ...

每个章节文件夹里的index.rst也要确保toctree的深度足够：

Chapter 1: 章节标题
===================

.. toctree::
    :maxdepth: 2
    :caption: 章节小节

    section1
    section2
    ...

内容的提问来源于stack exchange，提问作者user2882307