Sphinx docs / RST 包含来自动态路径的文件？答案

【问题标题】：Sphinx docs / RST include file from dynamic path?Sphinx docs / RST 包含来自动态路径的文件？
【发布时间】：2017-07-14 05:47:11
【问题描述】：

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

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

Some text in my RST file

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

Some more text

问题是另一个 repo 的相对路径并不总是相同的，这取决于克隆和安装的方式。例如，在 Read The Docs 中，另一个 repo 以可编辑模式通过 requirements.txt 安装到 /src 子文件夹中，本地 repo 位于 git 文件夹中，等等。

我可以将逻辑添加到 conf.py 文件中以查找另一个 repo 并设置一个我可以在 RST 文件中使用的指针，但我不知道是否可以在 @987654326 中有一个动态路径@?

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

【问题讨论】：

【解决方案1】：

在玩了一会儿之后，我决定创建一个软链接是要走的路。（起初我打算使用硬链接，但在 Read The Docs 上创建该链接失败。软链接适用于 RTD 和 Sphinx。）

所以我在 conf.py 中有代码，它遍历文件夹结构以找到我需要从中包含文件的另一个 repo，然后它创建链接（在首先删除旧链接并检查它找到的 repo 版本之后确保它是正确的）。然后我只是用软链接做..include::，一切都很好。

所以总体来说不是一个糟糕的解决方案，最重要的是它可以在本地和 RTD 上运行，并且无论其他 repo 的位置如何，它都可以正常工作。

【讨论】：