1.10.2. Substitutions¶
Substitutions are a useful way to define a value which is needed in many
places. Substitution definitions are indicated by an explicit markup start
(".. "
) followed by a vertical bar, the substitution text (which gets
substituted), another vertical bar, whitespace, and the definition block.
A substitution definition block may contain inline-compatible directives such as Images and Figures, Downloadable Files, or other Substitution Directives:
For more information, see reStructuredText Primer, section Substitutions, or refer the Substitution References. Sphinx provides additional predefined Substitutions.
-
.. replace::
¶ - The example
1 2 3
.. |RST| replace:: reStructuredText Here, :rst:`|RST|` will be replaced by |RST|.
- Which gives
Here,
|RST|
will be replaced by reStructuredText.
Styled Reference¶
You can also create a reference with styled text, nested inline markup.
- the example
1 2 3 4 5 6 7
.. |gh| replace:: :strong:`GitHub` .. _`gh`: https://github.com/ Here, :rst:`|gh|` will be replaced by |gh|. You can use the hyperlink reference by appending a :rst:`"_"` at the end of the vertical bars and :rst:`|gh|_` will be replaced by |gh|_.
- which gives
Here,
|gh|
will be replaced by GitHub.You can use the hyperlink reference by appending a
"_"
at the end of the vertical bars and|gh|_
will be replaced by GitHub.
Use Prolog and Epilog¶
The Sphinx configuration values rst_prolog
and
rst_epilog
in conf.py
contains a list of global
substitutions that can be used from any file. The (incomplete) list for this
document is given below:
"|project|"
→ leads to: “Li-Pro.Net Sphinx Primer”
"|author|"
→ leads to: “The LP/N Documentation Team”
"|publisher|"
→ leads to: “Li–Pro.Net”
"|copyright|"
→ leads to: “2020, Li–Pro.Net, The LP/N Documentation Team and individual contributors.”
"|LICENSE|"
→ leads to: “
LICENSE
”"|CREDITS|"
→ leads to: “
CREDITS
”
Inline Image¶
You can add inline images in the document using substitutions. The following block of code substitutes arrow in the text with the image specified.