How to define math symbols for use in text and formulae in RST markup?

Question

This question is related to writing technical documentation published on readthedocs.io using RST markup. I need to define "shortcut" symbols for mathemtatical symbols that can be re-used both in text and to write formulae in math blocks. The idea is to define the symbols only once, so that they can be used consistently across all documents.

Here's a non-working RST example to illustrate what I need:

define x1 = \x_1
define x2 = \x_2

The ratio of the two variables |x1| and |x2| is given by the following formula:
.. math::
        r = \frac{|x1|}{|x2|}

Obviously the RST commands and syntax are not quite right in this example. How can I make this work?

Answer 1

You found a general limitation of the rST format: Substitutions may contain inline markup (including a "math" role) but don't work inside "math" directives.

Inside "math" directives and roles you must use a syntax based on LaTeX math syntax, see LaTeX syntax for mathematics.

You may still want to define and use shortcuts in text and the expanded code in formulae:

.. |x1| replace:: :math:`x_1`
.. |x2| replace:: :math:`x_2`

The ratio of the two variables |x1| and |xi| is given by 

.. math:: r = \frac{x_1}{x_2}