Addressing reviewers' comments

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 main branch.
+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,10 +144,9 @@ are some formatting and style conventions that are used.
 Section formatting
 ~~~~~~~~~~~~~~~~~~
 
-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``
+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>`_
@@ -348,9 +347,10 @@ 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.)
+In rare cases we want the html output to correspond exactly with what will be
+generated in a Matplotlib figure. In these cases, you can use the
+`matplotlib.sphinxext.mathmpl` Sphinx extension (See also the
+:doc:`../tutorials/text/mathtext` tutorial.)
 
 .. _writing-docstrings:
 

galleries/users_explain/text/mathtext.py

@@ -58,9 +58,9 @@
    :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.
+   To generate html output in documentation that will exactly match the output
+   generated by ``mathext``, use the `matplotlib.sphinxext.mathmpl` Sphinx
+   extension.
 
 Subscripts and superscripts
 ---------------------------

lib/matplotlib/sphinxext/mathmpl.py

@@ -2,6 +2,11 @@
 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 write a given LaTeX string to Matplotlib (see
+:doc:`../tutorials/text/mathtext`).
+
 .. warning::
     In most cases, you will likely want to use one of `Sphinx's builtin Math
     extensions
@@ -10,11 +15,6 @@
     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:
 
 1. Inline, using the role::