如何在Sphinx中使用Doxygen HTML文件且不丢失导航面板层级

核心原因分析 #

点击:doc:链接后导航层级丢失，通常是因为Sphinx的toctree配置未正确维护文档层级结构，或是Doxygen生成的HTML未被正确整合到Sphinx的文档树中，导致侧边栏导航无法识别当前页面的层级位置。

具体解决方案 #

1. 规范toctree层级配置 #

在主文档（如index.rst）中，通过层级缩进定义文档结构，避免过度依赖:hidden:选项，同时设置合适的:maxdepth参数：

.. toctree::
   :maxdepth: 3  # 根据实际需求调整层级深度
   :caption: 文档导航

   module1/index
   module2/index
   doxygen_entry  # 指向整合Doxygen内容的入口.rst文件

如果你的4个.rst文件分属不同层级，需确保它们在toctree中正确嵌套，示例如下：

.. toctree::
   :maxdepth: 3

   overview
   tutorials/basic
   tutorials/advanced
   doxygen_docs/api_reference

2. 正确整合Doxygen内容到Sphinx文档树 #

不要直接用:doc:链接外部Doxygen HTML文件，推荐通过breathe扩展实现深度整合，让Sphinx识别Doxygen内容的层级：
在conf.py中配置breathe：

import breathe
breathe_projects = {"YourProject": "./doxygen/xml_output/"}
breathe_default_project = "YourProject"
extensions.append('breathe')

之后在.rst文件中使用.. doxygenclass::、.. doxygenfunction::等指令嵌入Doxygen生成的内容，而非直接跳转外部HTML。

若必须直接链接Doxygen HTML，需在conf.py中通过html_extra_path将Doxygen的HTML目录加入Sphinx的静态资源路径：

html_extra_path = ['./doxygen/html_output/']

同时在toctree中保留对应占位条目，维持导航层级的完整性。

3. 调整主题导航深度设置 #

部分Sphinx主题（如Read the Docs主题）的导航深度受html_theme_options控制，在conf.py中添加以下配置：

html_theme_options = {
    'navigation_depth': 4,  # 设置为覆盖你文档结构的层级数
}

4. 避免跨层级的:doc:跳转 #

如果:doc:链接的目标文档不在当前toctree的层级分支中，Sphinx侧边栏会重置导航层级。确保每个:doc:链接的目标都属于当前文档树的层级结构，或使用:glob:选项自动包含子目录文档：

.. toctree::
   :maxdepth: 3
   :glob:

   tutorials/*

验证步骤 #

修改配置后，重新执行sphinx-build生成文档，点击:doc:链接后检查侧边栏：

• 确认当前页面在导航树中处于正确层级位置
• 导航树的折叠/展开状态正常保留

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