Using Sphinx and reStructuredText, would it be possible to define math macros to make substitutions in a math Latex formula?
Basically, I would like to have something like
.. |bnabla| replace:: :math:`\boldsymbol{\nabla}`
.. |vv| replace:: :math:`\textbf{v}`
.. math:: \rho \mbox{D}_t |vv| = - |bnabla| p + \rho \textbf{g} + \eta |bnabla|^2 |vv|,
where |vv| is the velocity and |bnabla| is the nabla operator.
Then follow many other equations with |vv| and |bnabla|...
but it does not work at all. First the flags are not substituted in math mode and second, even if they were substituted, a :math:
statement does not work in a .. math::
block. Would it be a good idea and not to complicate to change these two behaviours in Sphinx?
Another solution would be to use latex macros as in this question Creating LaTeX math macros within Sphinx but I think the final code would be simpler to read with local rst substitutions as in my example. I would like to have clear formulas that can also be read in text mode.
Moreover, I am using the MathJax extension so I cannot use the variable pngmath_latex_preamble. I could use this solution for MathJax https://stackoverflow.com/a/19268549/1779806 but it seems quite complicate and once again the code would be clearer with "local" rst substitutions.
Edit:
I realized that it would be very convenient and useful for many people to implement a mathmacro
substitution directive directly in reStructuredText (i.e. in the Python package docutils). The new directive should work like this:
Definition:
.. |bnabla| mathmacro:: \boldsymbol{\nabla}
.. |vv| mathmacro:: \textbf{v}
These math macros could be included directly in text as in
|bnabla| is the nabla operator,
which should produce an inline equation like this
:math:`\boldsymbol{\nabla}` is the nabla operator.
These macros could also be included in inline equations:
This is an inline equation :math:`\vv = \bnabla f`,
which should be equivalent of
:math:`\textbf{v} = \boldsymbol{\nabla}f`
They could also be included in block equation
.. math:: \vv = \bnabla f
which should be equivalent of
.. math:: \textbf{v} = \boldsymbol{\nabla}f.
However, I am really not familiar with how docutils works internally. I notice in particular that the MathBlock directive (defined in docutils/parsers/rst/directives/body.py) does not call any parsing of its input so there is no substitution in math mode.
I do not know if it is possible to change the behaviour of a substitution directive such that the substitution is cleaver and adapt to the context from where it is call, in text, in inline math or in block math.
Does someone can give me some clues on how to implement this useful new feature?