如何在Sphinx同一项目的子目录中生成不同TOC？

root_doc无法设置多个值，它仅支持指定单个根文档，推荐以下几种可行的解决思路：

1. 为不同角色创建独立根文档 #

• 在source目录下新建三个根RST文件：user_contents.rst、admin_contents.rst、dev_contents.rst
• 每个文件通过toctree指令定义对应角色专属的目录结构，只包含目标受众需要的章节
• 构建时通过命令行参数指定对应root_doc：

  # 生成用户版文档
  sphinx-build -b html -D root_doc='user_contents' ./source ./build
  
  # 生成管理员版文档
  sphinx-build -b html -D root_doc='admin_contents' ./source ./adminbuild
  
  # 生成开发者版文档
  sphinx-build -b html -D root_doc='dev_contents' ./source ./devbuild
  

2. 用条件指令生成动态TOC #

• 保留单个contents.rst，通过Sphinx的only指令区分不同角色的TOC内容：

  .. only:: user
  
     .. toctree::
        :maxdepth: 2
  
        user_guide/intro
        user_guide/operations
  
  .. only:: admin
  
     .. toctree::
        :maxdepth: 2
  
        admin_guide/setup
        admin_guide/maintenance
  
  .. only:: dev
  
     .. toctree::
        :maxdepth: 2
  
        dev_guide/api
        dev_guide/contribute
  

• 构建时通过-t参数传递角色标签，触发对应条件块的渲染：

  # 用户版
  sphinx-build -b html -t user ./source ./build
  
  # 管理员版
  sphinx-build -b html -t admin ./source ./adminbuild
  
  # 开发者版
  sphinx-build -b html -t dev ./source ./devbuild
  

• 注意不要在conf.py中硬编码固定标签，确保标签仅通过构建命令传递。

3. 拆分配置文件 #

• 在source目录下创建三个专属配置文件：conf_user.py、conf_admin.py、conf_dev.py
• 每个配置文件先导入基础conf.py，再覆盖root_doc等专属参数：

  # conf_admin.py示例
  import conf
  
  # 继承基础配置
  globals().update(vars(conf))
  
  # 覆盖管理员版专属配置
  root_doc = 'admin_contents'
  

• 构建时指定对应配置文件：

  # 用户版
  sphinx-build -b html -c ./source ./source ./build -C conf_user.py
  
  # 管理员版
  sphinx-build -b html -c ./source ./source ./adminbuild -C conf_admin.py
  
  # 开发者版
  sphinx-build -b html -c ./source ./source ./devbuild -C conf_dev.py
  

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