Sphinx 文档/RST 包含来自动态路径的文件? [英] Sphinx docs / RST include file from dynamic path?

问题描述

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

I'm wondering if it's possible to use a dynamic path in a Sphinx and/or RST ..include:: directive?

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

My reason for this is I have some developer documentation generated by Sphinx in one repo, but we have a bunch of unit tests in another repo that we want to include in the docs. If I know the path to the file in the other repo, it's pretty standard, like this:

Some text in my RST file

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

Some more text

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

The problem is the relative path to the other repo is not always the same, depending on how things are cloned and installed. For example, on Read The Docs, the other repo is installed in editable mode via requirements.txt into a /src subfolder, locally the repo is in a git folder, etc.

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

I can add logic into the conf.py file to find the other repo and set a pointer which I can use in the RST files, but I can't figure out if it's possible to have a dynamic path in the ..include::?

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

So far the only workaround I can think of is to have my conf.py find the other repo and create a symlink which I reference in the RST files, which is fine, but I wonder if there's a better way?

推荐答案

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

After playing with this more for a bit, I decided that creating a soft link is the way to go. (At first I was going to use a hard link, but creating that fails on Read The Docs. Soft link works on RTD and in Sphinx.)

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

So I have code in conf.py that walks the folder structure to find the other repo I need to include files from, then it creates the link (after first removing the old one and checking the version of the repo it found to make sure it's the right one). Then I just do the ..include:: with the soft link and everything is fine.

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

So overall not a bad solution, and most importantly it works locally and on RTD, and it works regardless of the location of the other repo.

这篇关于Sphinx 文档/RST 包含来自动态路径的文件?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！