Merge pull request matplotlib#25221 from melissawm/mathmpl-docs

Add links and expand mathmpl docstring

Author: QuLogic

doc/devel/documenting_mpl.rst

@@ -55,7 +55,7 @@ build the documentation.
 Building the docs
 -----------------
 
-The documentation sources are found in the :file:`doc/` directory in the trunk.
+The documentation sources are found in the :file:`doc/` directory.
 The configuration file for Sphinx is :file:`doc/conf.py`. It controls which
 directories Sphinx parses, how the docs are built, and how the extensions are
 used. To build the documentation in html format, cd into :file:`doc/` and run:
@@ -144,9 +144,9 @@ are some formatting and style conventions that are used.
 Section formatting
 ~~~~~~~~~~~~~~~~~~
 
-For everything but top-level chapters,  use ``Upper lower`` for
-section titles, e.g., ``Possible hangups`` rather than ``Possible
-Hangups``
+Use `sentence case <https://apastyle.apa.org/style-grammar-guidelines/capitalization/sentence-case>`__
+``Upper lower`` for section titles, e.g., ``Possible hangups`` rather than
+``Possible Hangups``.
 
 We aim to follow the recommendations from the
 `Python documentation <https://devguide.python.org/documenting/#sections>`_
@@ -342,6 +342,16 @@ Note that the python script that generates the plot is referred to, rather than
 any plot that is created.  Sphinx-gallery will provide the correct reference
 when the documentation is built.
 
+Tools for writing mathematical expressions
+------------------------------------------
+
+In most cases, you will likely want to use one of `Sphinx's builtin Math
+extensions <https://www.sphinx-doc.org/en/master/usage/extensions/math.html>`__.
+In rare cases we want the rendering of the mathematical text in the
+documentation html to exactly match with the rendering of the mathematical
+expression in the Matplotlib figure. In these cases, you can use the
+`matplotlib.sphinxext.mathmpl` Sphinx extension (See also the
+:doc:`../users/explain/text/mathtext` tutorial.)
 
 .. _writing-docstrings:
 

galleries/users_explain/text/mathtext.py

@@ -57,6 +57,11 @@
    characters will behave differently depending on :rc:`text.usetex`.  See the
    :ref:`usetex tutorial <usetex>` for more information.
 
+.. note::
+   To generate html output in documentation that will exactly match the output
+   generated by ``mathtext``, use the `matplotlib.sphinxext.mathmpl` Sphinx
+   extension.
+
 Subscripts and superscripts
 ---------------------------
 To make subscripts and superscripts, use the ``'_'`` and ``'^'`` symbols::

lib/matplotlib/sphinxext/mathmpl.py

@@ -2,11 +2,18 @@
 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
+:ref:`mathtext`).
+
 .. warning::
     In most cases, you will likely want to use one of `Sphinx's builtin Math
     extensions
     <https://www.sphinx-doc.org/en/master/usage/extensions/math.html>`__
-    instead of this one.
+    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: