我们有一个用(优秀的)Sphinx 记录的多模块项目。我们的设置与 described on the mailing list 不同。 .总的来说这个works great !但我们对此有一些疑问:
子模块目录将包括索引链接。充其量这些将链接到错误的索引。 (在最坏的情况下,这似乎会触发 Sphinx 中的错误,但我使用的是开发版本,所以这是合理的)。有没有办法只为最顶层的目录树生成索引链接?
是否有让 Sphinx 配置在多个项目之间保持同步的最佳做法?我可以想象围绕
from common_config import *
一起破解一些东西,但对其他方法感到好奇。虽然我们正在处理它,但邮件列表帖子中提出的问题(替代符号链接(symbolic link)子项目文档?)从未得到回答。这对我来说不重要,但对其他读者可能很重要。
最佳答案
- 我不确定你的意思。您项目的 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>
我很确定这个方案会奏效,但我自己还没有测试过。
希望这会有所帮助!
关于python - 结合来自多个子项目的 Sphinx 文档 : Handling indices, 同步配置等,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/6334392/