在 Sphinx 的文件链接中使用版本号答案

【问题标题】：Use version number in file links in Sphinx在 Sphinx 的文件链接中使用版本号
【发布时间】：2015-09-04 10:10:21
【问题描述】：

在 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 中的版本号？

【问题讨论】：

标签： versioning python-sphinx

【解决方案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

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

【讨论】：

好消息 这在 HTML 中效果很好 坏消息 它不会在 PDF 中呈现为超链接（通过 latexpdf）。但至少它不会出错。