Add links and expand mathmpl docstring

Author: melissawm

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 in the main branch.
 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,7 +144,8 @@ are some formatting and style conventions that are used.
 Section formatting
 ~~~~~~~~~~~~~~~~~~
 
-For everything but top-level chapters,  use ``Upper lower`` for
+For everything but top-level chapters,  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``
 
@@ -342,6 +343,14 @@ 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.
 
+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>`__.
+However, to generate html output in documentation that will correspond to the
+same output generated by Matplotlib, use the `matplotlib.sphinxext.mathmpl`
+Sphinx extension (See also the :doc:`../tutorials/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 correspond to the same
+   output generated by ``mathext``, use the `matplotlib.sphinxext.mathmpl`
+   Sphinx extension.
+
 Subscripts and superscripts
 ---------------------------
 To make subscripts and superscripts, use the ``'_'`` and ``'^'`` symbols::

lib/matplotlib/sphinxext/mathmpl.py

@@ -6,7 +6,14 @@
     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 Sphinx built-in math directive uses MathJax to
+    render mathematical expressions, and addresses accessibility concerns that
+    ``mathmpl`` doesn't address.
+
+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 write a given LaTeX string to Matplotlib (see
+:doc:`../tutorials/text/mathtext`).
 
 Mathtext may be included in two ways: