Question

我们有一个记录了（优秀）Sphinx的多模块项目。我们的设置与described on the mailing list没有什么不同。总的来说这works great！但是我们有一些关于这样做的问题：

子模块目录将包含索引链接。充其量这些将链接到错误的指数。（在最坏的情况下，这似乎会触发Sphinx中的错误，但我正在使用devel版本，这是合理的）。有没有办法只为最顶层的toctree生成索引链接？
是否有保持Sphinx配置在多个项目之间同步的最佳做法？我可以想象在from common_config import *周围一起乱砍某些东西，但对其他方法感到好奇。
虽然我们在这里，但邮件列表中提出的问题（替代symlinking子项目文档？）从未得到回答。这对我来说并不重要，但对其他读者来说可能很重要。

Answer 1

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

我认为最好的方法是使用以下目录结构：

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点（包括常见配置），我正在使用：

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

请注意，与 @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

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

2 个答案: