如何让Sphinx文档的子小节在HTML输出中单独生成新页面

1. 调整文件存储结构 #

把需要单独分页的二级小节拆分为独立reST文件，最终文件结构参考如下：

docs/
├── index.rst                # 根文档
├── little_section.rst       # 一级页：Little section
├── big_section.rst          # 一级页：Big section
├── big_section_level2_1.rst # 独立二级页：Level 2 in a big section
├── big_section_level2_2.rst # 独立二级页：Another level 2 in a big section
└── another_little_section.rst # 一级页：Another little section

每个独立二级页的内容正常编写即可，文件内的首个标题就是小节本身的标题，无需额外调整层级。

2. 用hidden toctree绑定层级关系 #

打开big_section.rst文件，在内容任意位置（推荐放在末尾）添加带hidden参数的toctree指令，将两个独立二级页注册到当前一级页的子层级下：

.. toctree::
   :hidden:
   :maxdepth: 1

   big_section_level2_1
   big_section_level2_2

如果需要自定义边栏显示的条目文本，不用文件内默认的标题，可以用别名写法：

.. toctree::
   :hidden:
   :maxdepth: 1

   自定义显示的文本1 <big_section_level2_1>
   自定义显示的文本2 <big_section_level2_2>

这个配置的作用：

• 告知Sphinx两个二级页的父级是「Big section」，自动继承层级关系，不会被识别为一级页面
• 不会在big_section.rst的正文区域插入子页链接
• 不会产生orphan文件警告，不需要额外加:orphan:标记

3. 调整边栏导航显示深度 #

如果使用Read the Docs主题（sphinx_rtd_theme），打开项目配置文件conf.py，调整主题参数确保边栏能显示二级条目：

html_theme = 'sphinx_rtd_theme'
html_theme_options = {
    # 导航显示深度至少设为2，才能展示一级页下的子页条目
    'navigation_depth': 3,
    # 可选：关闭导航折叠，默认就能看到二级页条目
    'collapse_navigation': False,
}

如果使用其他Sphinx主题，查找对应主题的导航深度配置参数调整即可，只要允许显示二级导航条目，Sphinx会自动将hidden toctree下的子页渲染到父级页的导航下级。

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