Link a Sphinx substitution

Question

I have a Sphinx project, with some substitutions. I have a variable |total_downloads| (which works fine) on which I want to link some section statistics. I tried the following two pieces of code:

:ref:`|total_downloads| <statistics>`

and

:ref:`\ |total_downloads|\  <statistics>`

which both create correctly correctly the link, but display |total_downloads| instead of the content of the variable.

Is there any way to solve this issue? Thank you for your help!

Answer 1

The correct answer is in the comment, as @StevePiercy says, restructuredtext does not support anything other than plain text inside its links.

My advice would be to change it to say something like "1234 downloads (see full statistics <statistics>_)" so that both the information, and the link to the supporting section, are both clear.

Answer 2

While reStructuredText currently does not support nested inline markup, it allows the use of substitutions in simple hyperlink references:

.. |today| date::

Both, |today|__ and |today|_ produce a link with the current date as text.

__ example.com
.. _today: example.org  

I cannot tell, whether this also works for the |total_downloads| variable.

Hint: substitutions can also be used as a workaround to get emphasized or otherwise styled link text (see reStructuredText Directives).