在 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|

本质上是一个替代定义。当您在文档中使用 替换引用 时，它必须以

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|

，它们将在生成的输出中被它们的 raw-html 替换。

我尝试使用内联

:raw-html:

role 但这没有帮助，所以不幸的是，解决方案结果很冗长。

Answer 2

如上所述，上述内容不适用于 PDF，PDF 的解决方法是依靠 LaTeX 的强大功能，而不需要太复杂。

在你的

config.py

：

__version__ = 0.1 # Just an example of how to get it into the latex string dynamically
latex_prlog = rf"""
\newcommand{{\versionLink}}{{some.url.com/{__version__}}}
"""

如果我们使用格式化字符串，我们需要通过执行

{

和

}

来转义

{{

和

}}

，因为 LaTeX 使用这些字符串来定义函数。 （如果不需要字符串格式，则不要使用

f""

并省略双

{{ }}

并使用

{ }

代替。）

然后，在我们的文档中，我们可以生成链接：

Here's a version link :raw-latex:`\url{https://\versionLink}`.
It will have the same color throughout.