Sphinx项目侧边栏导航异常：如何实现所有页面显示全量文档

核心原因 #

你遇到的问题是因为默认情况下，Sphinx侧边栏的localtoc.html仅展示当前页面所属的局部目录结构，而非整个项目的完整文档列表。

便捷解决方案 #

步骤1：配置全局侧边栏模板 #

打开项目根目录下的conf.py，添加或修改html_sidebars配置，让所有页面加载全局目录模板：

html_sidebars = {
    '**': ['globaltoc.html', 'localtoc.html', 'searchbox.html']
}

• globaltoc.html：渲染整个项目的完整文档目录（基于你在index.rst中定义的主toctree）
• localtoc.html：保留当前页面的局部目录（可选，可根据需求移除）
• searchbox.html：保留搜索功能（可选）

步骤2：维护主toctree #

确保index.rst中的主toctree包含所有需要展示的文档：

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   firstdoc
   seconddoc

后续新增文档时，只需在这个主toctree中添加新文档的文件名，无需修改其他页面。

可选：自动匹配文档 #

如果想避免手动添加新文档，可以给主toctree加上:glob:选项，自动匹配指定模式的文件：

.. toctree::
   :maxdepth: 2
   :caption: Contents:
   :glob:

   *.rst

该配置会自动将所有.rst格式的文档加入目录，注意调整匹配模式以符合你的项目结构，避免包含无关文件。

验证效果 #

执行make html重新构建项目，部署后所有页面的侧边栏都会显示完整的项目文档列表。

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