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

Question

我们有一个用(优秀的)Sphinx记录的多模块项目.我们的设置与邮件列表中描述的设置没有什么不同.总的来说这很棒!但是我们有一些关于这样做的问题:

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

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

3. 虽然我们在这里,但邮件列表中提出的问题(替代symlinking子项目文档？)从未得到回答.这对我来说并不重要,但对其他读者来说可能很重要.

Answer 1

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>
   

   我很确定这个计划会奏效,但我还没有自己测试一下.

希望这可以帮助!