Sphinx 文档/RST 包含动态路径中的文件？

Question

我想知道是否可以在 Sphinx 和/或 RST..include::指令中使用动态路径？

我这样做的原因是我在一个存储库中拥有 Sphinx 生成的一些开发人员文档，但我们在另一个存储库中有一堆单元测试，我们希望将其包含在文档中。如果我知道其他存储库中文件的路径，那么它是非常标准的，如下所示：

Some text in my RST file

.. include:: ../path/to/other/repo/file.py
:code: python

Some more text

问题是其他存储库的相对路径并不总是相同，具体取决于克隆和安装的方式。例如，在阅读文档时，另一个存储库通过子文件夹以可编辑模式安装requirements.txt，/src本地存储库位于 git 文件夹中，等等。

我可以在conf.py文件中添加逻辑来查找其他存储库并设置一个可以在 RST 文件中使用的指针，但我无法弄清楚是否可以在..include::?

到目前为止，我能想到的唯一解决方法是让我conf.py找到另一个存储库并创建一个我在 RST 文件中引用的符号链接，这很好，但我想知道是否有更好的方法？

Answer 1

在玩了一会儿之后，我决定创建一个软链接是正确的方法。（起初我打算使用硬链接，但在阅读文档时创建失败。软链接适用于 RTD 和 Sphinx。）

因此，我在 conf.py 中有代码，它遍历文件夹结构以查找我需要包含文件的其他存储库，然后创建链接（在首先删除旧的并检查它找到的存储库的版本以确保它是正确的那一个）。然后我只需使用..include::软链接即可，一切都很好。

因此，总的来说，这是一个不错的解决方案，最重要的是，它可以在本地和 RTD 上运行，并且无论其他存储库的位置如何，它都可以运行。