Sphinx Autodoc生成的TOC未列出子包问题排查

核心问题是自动生成的API文档根文件modules.rst没有接入index.rst的全局toctree树，这也是构建时出现WARNING: document isn't included in any toctree警告的直接原因。Read the Docs主题的侧边栏全局导航完全依赖根文档定义的嵌套toctree结构，未接入全局树的页面，侧边栏只会渲染当前页的局部目录，自然无法展示完整的包层级路径。
另外当前配置还有两个冗余/错误点：

• 执行sphinx-apidoc时传入的根路径错误，导致生成的modules.rst把src作为根层级，不符合实际包结构
• conf.py里重复添加了所有子包的系统路径，实际上Python导入机制会自动递归识别src目录下的子包，多余路径反而可能引发模块解析异常

• 修改根文档doc/index.rst，把modules加入全局toctree，替换原来空的toctree块：

  .. toctree::
     :maxdepth: 4
     :caption: Contents:
  
     modules
  

• 重新生成API文档，修正apidoc的执行路径，在doc目录下执行以下命令，避免生成多余的src根层级：

  sphinx-apidoc -f -o . ../src/dashtutorial
  

  执行后新生成的modules.rst会自动递归包含dashtutorial.data、dashtutorial.gui、dashtutorial.gui.components等所有子包的文档条目，不需要手动维护。
• 精简doc/conf.py里的路径配置，只保留src目录的路径即可：

  import os
  import sys
  sys.path.insert(0, os.path.abspath('../src'))
  

• （可选，针对侧边栏折叠问题）在conf.py中添加RTD主题配置，强制展示完整层级导航：

  html_theme_options = {
      'navigation_depth': 4,
      'collapse_navigation': False,
      'titles_only': False
  }
  

所有修改完成后，在doc目录下执行make clean && make html重新构建，之前的toctree警告会消失，打开生成的HTML页面即可在侧边栏看到完整的包路径TOC结构，跳转任意子页面时侧边栏也会保留全局导航。

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