在Sphinx中通过扩展自动添加嵌套侧边栏TOC条目遇异常

问题场景 #

使用Sphinx扩展基于目录内容自动给侧边栏TOC添加条目时，当前章节内的TOC节点显示正常，但嵌套的附加条目（如带TOC的新索引文件）无法在侧边栏显示。导航到section4时，页面内部能看到TOC节点，但侧边栏里没有这些嵌套项，使用的是Sphinx Book主题。

内容结构 #

Core Section
-section1
-section2
-section3
-section4
---nested1
---nested2
---nested3

当前核心代码 #

entries = []
includefiles = []
for subfile in folder:
    entries.append([file.title, file.docname])
    includefiles.append(file.docname)
tocnode = addnodes.toctree(parent=self.env.docname, glob=False, entries=entries, includefiles=includefiles)

解决步骤 #

1. 调整toctree节点参数并更新全局TOC #

Sphinx Book主题的侧边栏TOC依赖全局文档结构，仅在页面内添加toctree节点不足以让主题识别。需要修改代码，确保生成的条目被注入全局TOC：

entries = []
includefiles = []
for subfile in folder:
    # 修正原代码变量名不匹配问题
    entries.append([subfile.title, subfile.docname])
    includefiles.append(subfile.docname)

# 创建toctree节点时指定maxdepth确保显示所有层级
tocnode = addnodes.toctree(
    parent=self.env.docname,
    glob=False,
    entries=entries,
    includefiles=includefiles,
    maxdepth=-1  # -1表示显示所有嵌套层级
)

# 将节点添加到当前文档内容
self.state.append(tocnode)

# 更新全局TOC结构，让主题能抓取到这些条目
if self.env.docname not in self.env.tocs:
    self.env.tocs[self.env.docname] = tocnode
else:
    # 追加到现有TOC节点中
    self.env.tocs[self.env.docname].extend(tocnode)

2. 调整主题配置显示深度 #

在conf.py里设置足够的导航深度，确保嵌套层级能被显示：

html_theme_options = {
    "navigation_depth": 3,  # 根据实际嵌套层级调整数值
    "show_toc_level": 3,
}

3. 排除文件孤儿属性 #

确保嵌套文件的开头没有设置:orphan:标记，这个属性会让文件被排除在全局TOC之外。

4. 验证文档路径正确性 #

检查subfile.docname是否为正确的相对路径（相对于Sphinx的source目录），路径错误会导致主题无法找到对应文档。

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