如何在Sphinx侧边栏显示根文档章节（Read The Docs主题）

问题背景 #

使用Sphinx HTML构建器搭配Read The Docs主题构建组件化技术文档，每个页面对应一个组件，组件可关联子组件。当前Sphinx默认将根文档（index.rst）视为纯目录页，导致侧边栏无法显示根文档自身的章节层级（如Subcomponents、Section A等）。尝试过虚拟根文档、隐藏toctree方案，均存在导航异常、样式兼容、层级显示不符合预期等问题。

根文档示例代码：

Component 1
***********

Subcomponents
=============

.. toctree::
    component_2
    component_4

Section A
=========

Subsection a
^^^^^^^^^^^^

Subsubsection i
~~~~~~~~~~~~~~~

期望效果：侧边栏同时显示根文档的章节层级，且正确嵌套子组件的导航内容。

可行解决方案 #

1. 强制根文档加载本地目录侧边栏 #

在项目的conf.py中修改html_sidebars配置，让根文档同时加载全局目录和本地目录：

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

• 原理：默认情况下根文档仅加载globaltoc.html（全局子组件导航），添加localtoc.html后会显示根文档自身的章节层级。
• 优势：无需修改文档内容，配置简单，样式完全兼容RTD主题。

2. 隐藏toctree+手动关联子组件 #

调整根文档的结构，用隐藏的toctree保证子组件被纳入全局导航，同时手动添加子组件链接到章节中：

Component 1
***********

Subcomponents
=============

.. toctree::
    :hidden:
    :titlesonly:

    component_2
    component_4

- Component 2
- Component 4

Section A
=========

Subsection a
^^^^^^^^^^^^

Subsubsection i
~~~~~~~~~~~~~~~

• 原理：隐藏的toctree会让子组件出现在全局导航中，手动添加的链接让根文档的章节内容更完整，同时侧边栏的localtoc会显示根文档的所有层级。
• 优势：根文档内容和导航分离，避免toctree破坏章节结构。

3. 自定义RTD主题侧边栏模板 #

如果前两种方法无法满足需求，可自定义主题模板：

1. 在项目根目录创建_templates文件夹
2. 复制RTD主题的globaltoc.html模板文件到该文件夹（可在Python的site-packages中找到RTD主题的模板目录）
3. 修改模板内容，在根文档页面优先显示自身章节：

{% if pagename == 'index' %}
  {{ toc }}
{% endif %}
{{ globaltoc }}

• 原理：通过模板逻辑判断当前是否为根文档，若是则先渲染根文档的章节目录，再渲染全局子组件导航。
• 优势：完全自定义侧边栏结构，适配复杂的文档层级需求。

是否需要提交功能请求？ #

如果以上方案都无法满足你的具体需求，可以向Sphinx提交功能请求。提交时请明确说明：

• 场景：组件化递归文档，根文档需要同时作为内容页和目录入口
• 当前缺陷：默认配置下根文档无法同时显示自身章节和子组件导航
• 已尝试的方案及缺陷
  这能帮助Sphinx开发团队更快理解并评估需求。

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