versioning - 在 Sphinx 中的文件链接中使用版本号

Question

在 Sphinx 中，可以使用以下语法生成文件链接:

`name_of_file.js <some/location/name_of_file.js>`_

在 conf.py 文件中，一个 version定义了我们可以在 .rst 文件中使用的变量，如下所示:

|version|

不允许使用该语法将版本包含在文件链接中:

`name_of_file.|version|.min.js <some/location/name_of_file.|version|.min.js>`_

那么，我如何生成名为 name_of_file.<version_num>.min.js 之类的文件的链接并使用 conf.py 中的版本号？

Answer 1

我需要类似的东西，经过多次实验，我有一个解决方法。请注意，这是一个糟糕的解决方案，但它有效。

简答:

您需要将链接的部分拆分为 |version| 的左侧和右侧。并使用原始 html 和 |version| .您的 .rst 将如下所示:

Example of a link with version in it |link-pre|\ |version|\ |link-post|

.. |link-pre| raw:: html

    <a href="some/location/name_of_file.

.. |link-post| raw:: html

    .min.js">name_of_file.min.js</a>

长答案

我们需要克服几个障碍:

问题1:
现在， |version|本质上是一个 substitution definition .当您使用 substitution reference在您的文档中，它必须以 space 开头像这样 |version| .

因此，即使在不是链接的常规 rsT 语句中，您也不能执行 name_of_file.|version|.min.js .您需要做 name_of_file.\ |version|.min.js ，即逃避 space与 \
问题 2:reST 不支持嵌套内联标记: http://docutils.sourceforge.net/FAQ.html#is-nested-inline-markup-possible

所以你不能换人， |version| , 在链接内 \`name_of_file.|version|.min.js`\ .这就是为什么我们必须使用 raw-html 并将其分成几部分，并且我们创建了另外 2 个替换定义 |link-pre|和 |link-post| ，它将在生成的输出中替换为原始 html。

我尝试使用内联 :raw-html: role但这并没有帮助，所以不幸的是，解决方案变得冗长。