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

Question

我们有一个多模块的项目记录（优秀）狮身人面像。我们的设置和described on the mailing list没有什么不同。总的来说这是works great！但我们有几个问题要问：

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

2. 是否有在多个项目之间保持Sphinx配置同步的最佳实践？我可以想象在from common_config import *周围一起进行黑客攻击，但对其他方法很好奇。

3. 当我们在做的时候，邮件列表中提出的问题（除了符号链接子项目文档之外？）没有人回答。这对我不重要，但对其他读者可能很重要。

Answer 1

关于第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

Answer 2

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>
   

   我很肯定这个计划会成功的，但我自己还没有试过。

希望这有帮助！