[Docutils-users] implementing a ``mathmacro`` substitution directive?

[Pierre <pie...@en...>]

Hello,

I am struggling to write a documentation with a lot of math. It would be
very convenient to implement a ``mathmacro`` substitution directive which
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 like this::

    This is an inline equation :math:`|vv| = |bnabla|f`, 

  which should give :math:`\textbf{v} = \boldsymbol{\nabla}f`.

- They could also be included in block equation::

    .. math:: |vv| = |bnabla|f

  which should gives

  .. math:: \textbf{v} = \boldsymbol{\nabla}f.

Would it be possible to do that?

I think it would be a lot nicer to use such mathmacro directive rather that
latex macros since (i) it would leads to nicer code and (ii) the MathJax
sphinx extension does not really supports macro definition.

I'm trying to define a new directive by copying on the replace directive but
I don't know how to redefine the substitution rules (which have to vary
depending on the context, in text, in inline math and in block math). I
don't know neither if rST can work this way, with a directive preprocessing
text that will be used after by math directives.