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

Question

我们有一个多模块的项目，使用了很棒的 Sphinx 来做文档。我们的设置和一个在邮件列表上描述的情况差不多。总体来说，这个方法运行得很好！不过我们有几个问题想要了解：

1. 子模块的目录会包含索引链接。最好的情况是这些链接指向错误的索引。最糟糕的情况是这似乎会引发 Sphinx 的一个错误，但我用的是开发版本，所以这也算正常。有没有办法只为最上层的目录生成索引链接呢？

2. 在多个项目之间，保持 Sphinx 配置同步有没有什么最佳实践？我可以想象用 from common_config import * 来搞定，但我也想知道有没有其他的方法。

3. 顺便提一下，邮件列表中提到的问题（有没有替代的方法来链接子项目文档？）一直没有得到回答。对我来说这不是很重要，但可能对其他读者来说很重要。

Answer 1

关于第二点（包括常见配置），我使用的是：

在 Python 2 中：

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

在 Python 3 中：

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

需要注意的是，与@DangerOnTheRanger展示的目录结构不同，我更喜欢为常见文档保留一个单独的目录，这就是为什么上面的路径中有common这个文件夹。

我的 common/conf.py 文件是一个普通的 Sphinx 文件。然后，每个具体的文档配置都会包含这个公共文件，并根据需要覆盖一些值，就像这个例子：

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

Answer 2

1. 我不太明白你说的是什么意思。你的项目的索引看起来没问题。能不能再解释一下呢？
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>
   

   我很确定这个方案是可行的，但我还没亲自测试过。

希望这能帮到你！