A role and directive to display mathtext in Sphinx#

The mathmpl Sphinx extension creates a mathtext image in Matplotlib and shows it in html output. Thus, it is a true and faithful representation of what you will see if you pass a given LaTeX string to Matplotlib (see Writing mathematical expressions).


In most cases, you will likely want to use one of Sphinx's builtin Math extensions instead of this one. The builtin Sphinx math directive uses MathJax to render mathematical expressions, and addresses accessibility concerns that mathmpl doesn't address.

Mathtext may be included in two ways:

  1. Inline, using the role:

    This text uses inline math: :mathmpl:`\alpha > \beta`.

    which produces:

    This text uses inline math: .

  2. Standalone, using the directive:

    Here is some standalone math:
    .. mathmpl::
        \alpha > \beta

    which produces:

    Here is some standalone math:


The mathmpl role and directive both support the following options:

fontsetstr, default: 'cm'

The font set to use when displaying math. See rcParams["mathtext.fontset"] (default: 'dejavusans').


The font size, in points. Defaults to the value from the extension configuration option defined below.

Configuration options#

The mathtext extension has the following configuration options:

mathmpl_fontsizefloat, default: 10.0

Default font size, in points.

mathmpl_srcsetlist of str, default: []

Additional image sizes to generate when embedding in HTML, to support responsive resolution images. The list should contain additional x-descriptors ('1.5x', '2x', etc.) to generate (1x is the default and always included.)

class matplotlib.sphinxext.mathmpl.MathDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]#

The .. mathmpl:: directive, as documented in the module's docstring.

final_argument_whitespace = False#

May the final argument contain whitespace?

has_content = True#

May the directive have content?

option_spec = {'fontset': <function fontset_choice>, 'fontsize': <function _make_type_validator.<locals>.validate_float_or_None>}#

Mapping of option names to validator functions.

optional_arguments = 0#

Number of optional arguments after the required arguments.

required_arguments = 0#

Number of required directive arguments.