结合来自多个子项目的 Sphinx 文档：处理索引、同步配置等

Question

我们有一个用（优秀的）Sphinx 记录的多模块项目。我们的设置与described on the mailing list 不同。总的来说这个works great！但我们对此有一些疑问：

1. 子模块目录将包括索引链接。充其量这些将链接到错误的索引。 （在最坏的情况下，这似乎会触发 Sphinx 中的错误，但我使用的是开发版本，所以这是合理的）。有没有办法只为最顶层的目录树生成索引链接？

2. 是否有在多个项目之间保持 Sphinx 配置同步的最佳实践？我可以想象在from common_config import * 周围一起破解一些东西，但对其他方法感到好奇。

3. 虽然我们正在处理它，但邮件列表帖子中提出的问题（替代符号链接子项目文档？）从未得到回答。这对我来说不重要，但对其他读者可能很重要。

Answer 1

1. 我不确定你的意思。您的项目的index 似乎很好。请您澄清一下好吗？
2. 就我所见，from common_config import * 是保持配置同步的最佳方法。

3. 我认为最好的方法是如下目录结构：

   main-project/
    conf.py
    documentation.rst
   
    sub-project-1/
       conf.py - imports from main-project/conf.py
       documentation.rst
   
    sub-project-2/
       conf.py - likewise, imports from main-project/conf.py
       documentation.rst
   

   然后，要打包 sub-project-1 或 sub-project-2，请使用以下 UNIX 命令：

   sphinx-build main-project/ <output directory> <paths to sub-project docs you want to add>
   

   这样，不仅会构建主项目的文档，还会添加您要添加​​的子项目文档。

   要打包main-project:

   sphinx-build main-project/ <output directory>
   

   我很确定这个方案会奏效，但我还没有亲自测试过。

希望这会有所帮助！

Answer 2

关于第2点（包括通用配置），我使用的是：

在 Python 2 中：

execfile (os.path.abspath("../../common/conf.py"))

在 Python 3 中：

exec (open('../../common/conf.py').read())

请注意，与@DangerOnTheRanger 提供的目录结构不同，我更喜欢为常用文档保留一个单独的目录，这就是common 出现在上述路径中的原因。

我的 common/conf.py 文件是一个普通的 Sphynx 文件。然后，每个特定的文档配置都包含该公共文件并根据需要覆盖值，如下例所示：

import sys
import os

execfile (os.path.abspath("../../common/conf.py"))

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.todo',
    'sphinx.ext.viewcode',
]

# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True

# If true, links to the reST sources are added to the pages.
html_copy_source = False
html_show_sourcelink = False