组合来自多个子项目的Sphinx文档：处理索引，同步配置等 [英] Combining Sphinx documentation from multiple subprojects: Handling indices, syncing configuration, etc

问题描述

我们有一个多模块项目记录与（优秀）狮身人面像。我们的设置与在邮件列表中描述的不同。总体来说，的效果非常好！但是我们有一些关于这样做的问题：

1. 内容的子模块表将包括索引链接。最好这些链接到错误的索引。 （最糟糕的是，这似乎在Sphinx中引发了一个错误，但是我正在使用devel版本，这是合理的）。有没有一种方法可以为最高的toctree生成索引链接？




2. 有没有最好的做法来保持Sphinx配置在多个项目之间同步？我可以想象一下，从common_config import * 中围绕一起骇客，但对其他方法很好奇。




3. 我们在这里，在邮件列表中提出的问题（替代符号链接子项目文档？）从未回答过。这对我来说并不重要，但对其他读者来说可能很重要。




解决方案

ol>


我不知道这是什么意思。您的项目的索引似乎很好。您可以澄清一下吗？




据我所见，common_config import * 中的是保持配置同步。




我认为最好的方式是这样的目录结构：

  main-project / 
 conf.py 
 documentation.rst 
 
 sub-project-1 / 
 conf.py  - 从main-project / conf.py 
 documentation.rst 
 
 sub-project-2 / 
 conf.py  - 同样，从main-project / conf.py $ b $导入b document.rst 
  

然后，只需打包 sub-project-1 或 sub-project-2 ，使用这个UNIX命令：

 code> sphinx-build main-project /< output directory> <要添加到子项目文档的路径> 
  

这样，不仅主项目文档的构建，您想要的子项目文档添加将被添加。

要打包 main-project ：

  sphinx-build main-project /< output directory> 
  

我很确定这个方案可以工作，但我还没有自己测试。

希望这有帮助！

We have a multi-module project documented with the (excellent) Sphinx. Our setup is not unlike one described on the mailing list. Overall this works great! But we have a few questions about doing so:

1. The submodule tables of contents will include index links. At best these will link to the wrong indices. (At worst this seems to trigger a bug in Sphinx, but I'm using the devel version so that's reasonable). Is there a way of generating the index links only for the topmost toctree?

2. Are there best practices for keeping the Sphinx configuration in sync between multiple projects? I could imagine hacking something together around from common_config import *, but curious about other approaches.

3. While we're at it, the question raised in the mailing list post (alternative to symlinking subproject docs?) was never answered. It's not important to me, but it may be important to other readers.

解决方案

1. I'm not sure what you mean by this. Your project's index appears to be just fine. Could you clarify on this, please?
2. As far as I've seen, from common_config import * is the best approach for keeping configuration in sync.

3. I think the best way to do this is something like the following directory structure:

   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
   

   Then, to just package sub-project-1 or sub-project-2, use this UNIX command:

   sphinx-build main-project/ <output directory> <paths to sub-project docs you want to add>
   

   That way, not only will the main project's documentation get built, the sub-project documentation you want to add will be added as well.

   To package main-project:

   sphinx-build main-project/ <output directory>
   

   I'm pretty sure this scheme will work, but I've yet to test it out myself.

Hope this helps!

这篇关于组合来自多个子项目的Sphinx文档：处理索引，同步配置等的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！