CODEWITHSUNDEEP
python-sphinxsubstitutionrestructuredtext
José Ramón
José Ramón

Reputation: 182

Nested substitutions in sphinx

I am creating my documentation in Sphinx (I am learning the basics still). In my project there are some files with very long names and I refer to them in my document many times, so, to make my life easier, I decided to use substitutions like this:

.. |MyFile| replace:: a_very_very_long_name_for_a_file_v2.0.txt

And then I just type |MyFile| anywhere I want to refer to that file. That works just fine, but now I would like to make the version part variable, so I don't have to change all my aliases when I make a new release (I'm sure I would forget something). Luckily Sphinx sets the variable version so I tried:

.. |MyFile| replace:: a_very_very_long_name_for_a_file_v |version| .txt

But that nested replacement is ignored. I've been googling for more than an hour now and I am surprised no one has asked this before. I've seen something about Parsed Literals but I couldn't make it work. Make an alias based on other alias should be something quite common, right? Am I missing something? Is there a better approach for this?

Upvotes: 4

Views: 1684

Answers (1)

mzjn
mzjn

Reputation: 51052

It works for me. Have you set version to 2.0 in conf.py?

Substitution definition: 

.. |MyFile| replace:: a_very_very_long_name_for_a_file_v\ |version|\ .txt

Output when using the |MyFile| reference:

a_very_very_long_name_for_a_file_v2.0.txt

Note that the whitespaces before and after |version| are escaped in order to exclude them from the output (see http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#escaping-mechanism).

Upvotes: 6

Related Questions