fluiddoc.mathmacro

Sphinx extension providing a new directive mathmacro

This extension has to be added after the other math extension since it redefined the math directive and the math role. For example, like this (in the conf.py file):

extensions = [
    'sphinx.ext.autodoc', 'sphinx.ext.doctest',
    'sphinx.ext.mathjax',
    'sphinx.ext.viewcode', 'sphinx.ext.autosummary',
    'numpydoc',
    'fluiddoc.mathmacro']

Here, I show how to use a new mathmacro substitution directive in reStructuredText. I think even this small example demonstrates that it is useful.

Example

First some math without math macros. Let’s take the example of the incompressible Navier-Stokes equation:

\[\mbox{D}_t \textbf{v} = -\boldsymbol{\nabla} p + \nu \boldsymbol{\nabla} ^2 \textbf{v}.\]

where \(\mbox{D}_t\) is the convective derivative, \(\textbf{v}\) the velocity, \(\boldsymbol{\nabla}\) the nabla operator, \(\nu\) the viscosity and \(\boldsymbol{\nabla}^2\) the Laplacian operator.

The code for this is:

.. math::
  \mbox{D}_t \textbf{v} =
  -\boldsymbol{\nabla} p + \nu \boldsymbol{\nabla} ^2 \textbf{v}.

where :math:`\mbox{D}_t` is the convective derivative, :math:`\textbf{v}` the
velocity, :math:`\boldsymbol{\nabla}` the nabla operator, :math:`\nu` the
viscosity and :math:`\boldsymbol{\nabla}^2` the Laplacian operator.

Now, let’s use some math macros and try to get the same result… We use the following code:

The Navier-Stokes equation can now be written like this:

.. math:: \Dt \vv = - \bnabla p + \nu \bnabla^2 \vv

where |Dt| is the convective derivative, |vv| the velocity, |bnabla| the nabla
operator, :math:`\nu` the viscosity and :math:`\bnabla^2` the Laplacian operator.

It gives:

The Navier-Stokes equation can now be written like this:

\[\mbox{D}_t \textbf{v} = - \boldsymbol{\nabla} p + \nu \boldsymbol{\nabla}^2 \textbf{v}\]

where \(\mbox{D}_t\) is the convective derivative, \(\textbf{v}\) the velocity, \(\boldsymbol{\nabla}\) the nabla operator, \(\nu\) the viscosity and \(\boldsymbol{\nabla}^2\) the Laplacian operator.

Functions

multiple_replace(string, replace_dict)
multiple_replacer(replace_dict)	Return a function replacing doing multiple replacements.
new_math_role(role, rawtext, text, lineno, ...)	New math role parsing the latex code.
setup(app)

Classes

MathMacro(name, arguments, options, content, ...)	Directive defining a math macro.
NewMathDirective(name, arguments, options, ...)	New math block directive parsing the latex code.