python - 结合来自多个子项目的 Sphinx 文档 : Handling indices, 同步配置等

Question

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

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

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

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

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>
   

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

希望这会有所帮助!