在 Sphinx 中的文件链接中使用版本号 [英] Use version number in file links in Sphinx

问题描述

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

In Sphinx, file links can be generated using the following syntax:

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

在 conf.py 文件中，定义了一个 version 变量，我们可以像这样在 .rst 文件中使用:

In the conf.py file, a version variable is defined that we can use in the .rst files like such:

|version|

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

Including the version into the file link using that syntax is not allowed:

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

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

So, how can I generate links to files named something like name_of_file.<version_num>.min.js and use the version number from conf.py?

推荐答案

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

I had a need for something similar and after much experimentation I have a workaround for this. Be warned, this is a crummy solution but it works.

简短的回答:

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

You need to split the parts of the link to left and right of |version| and use raw html along with the |version|. Your .rst will look like this:

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>

长答案

我们需要克服几个障碍:

There are a couple of hurdles we need to overcome:

问题 1:现在，|version| 本质上是一个 替代定义.当您在文档中使用 替代参考时，它必须以 space 开头，就像 |version| 一样.

Problem 1: Now, |version| is essentially a substitution definition. When you use a substitution reference in your document, it has to lead with a space like so |version|.

因此，即使在不是链接的常规 rsT 语句中，您也无法执行 name_of_file.|version|.min.js.您需要执行 name_of_file.\ |version|.min.js，即使用 \

So even in a regular rsT sentence, which is not a link, you can't do name_of_file.|version|.min.js. You will need to do name_of_file.\ |version|.min.js, i.e, escape the space with a \

问题 2:reST 不支持嵌套内联标记:http://docutils.sourceforge.net/FAQ.html#is-nested-inline-markup-possible

Problem 2: Nested inline markup is not supported in reST: http://docutils.sourceforge.net/FAQ.html#is-nested-inline-markup-possible

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

So you can't make a substitution, |version|, within a link \`name_of_file.|version|.min.js`\. This is why we have to use raw-html and break it into parts, and we create 2 more substitution definitions |link-pre| and |link-post|, which will be replaced with their raw-html in the generated output.

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

I tried using inline :raw-html: role but that did not help, so unfortunately the solution turned out to be verbose.

这篇关于在 Sphinx 中的文件链接中使用版本号的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！