Use version number in reference files in Sphinx
In Sphinx, file links can be generated using the following syntax:
`name_of_file.js <some/location/name_of_file.js>`_
The conf.py file defines a variable version
that we can use in .rst files such as:
|version|
Including a version in a file link using this syntax is not allowed:
`name_of_file.|version|.min.js <some/location/name_of_file.|version|.min.js>`_
So how can I generate links to files named like name_of_file.<version_num>.min.js
and use the version number from conf.py?
source to share
I needed something like this and after a lot of experimentation I have a workaround for this. Be careful, this is a tricky solution, but it works.
The short answer is:
You need to split the parts of the link to the left and right of | versions | and use raw html along with |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>
Long answer
There are several obstacles we need to overcome:
Problem 1: Now |version|
essentially a replacement for the definition . When you use the link to fill in your document, it must lead by using space
, for example |version|
.
So, even in a regular rsT clause that is not a link, you cannot do name_of_file.|version|.min.js
. You will need to do name_of_file.\ |version|.min.js
i.e. Exit space
with\
Issue 2: Nested inline markup is not supported in the registry: http://docutils.sourceforge.net/FAQ.html#is-nested-inline-markup-possible
Thus, you cannot make a replacement, |version|
within the reference \`name_of_file.|version|.min.js`\
. This is why we have to use raw-html and break it apart and we create 2 more substitution definitions |link-pre|
and |link-post|
that will be replaced with their raw-html in the generated release.
I tried using an inline :raw-html:
role but that didn't help, so unfortunately the solution turned out to be verbose.
source to share