8000 Merge pull request #25221 from melissawm/mathmpl-docs · matplotlib/matplotlib@c8aaa90 · GitHub
[go: up one dir, main page]
Skip to content

Commit c8aaa90

Browse files
QuLogicQuLogic
authored
Merge pull request #25221 from melissawm/mathmpl-docs
Add links and expand mathmpl docstring
2 parents d21b9dc + ab8949b commit c8aaa90

File tree

3 files changed

+27
-5
lines changed
  • < 8000 div class="PRIVATE_TreeView-item-toggle PRIVATE_TreeView-item-toggle--end prc-TreeView-TreeViewItemToggle-gWUdE prc-TreeView-TreeViewItemToggleHover-nEgP- prc-TreeView-TreeViewItemToggleEnd-t-AEB">
    doc/devel
  • galleries/users_explain/text
  • lib/matplotlib/sphinxext

    • 3 files changed

    +27
    -5
    lines changed

    ‎doc/devel/documenting_mpl.rst

    Lines changed: 14 additions & 4 deletions
    Original file line numberDiff line numberDiff line change
    @@ -55,7 +55,7 @@ build the documentation.
    5555
    Building the docs
    5656
    -----------------
    5757

    < 8000 /td>
    58-
    The documentation sources are found in the :file:`doc/` directory in the trunk.
    58+
    The documentation sources are found in the :file:`doc/` directory.
    5959
    The configuration file for Sphinx is :file:`doc/conf.py`. It controls which
    6060
    directories Sphinx parses, how the docs are built, and how the extensions are
    6161
    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.
    144144
    Section formatting
    145145
    ~~~~~~~~~~~~~~~~~~
    146146

    147-
    For everything but top-level chapters, use ``Upper lower`` for
    148-
    section titles, e.g., ``Possible hangups`` rather than ``Possible
    149-
    Hangups``
    147+
    Use `sentence case <https://apastyle.apa.org/style-grammar-guidelines/capitalization/sentence-case>`__
    148+
    ``Upper lower`` for section titles, e.g., ``Possible hangups`` rather than
    149+
    ``Possible Hangups``.
    150150

    151151
    We aim to follow the recommendations from the
    152152
    `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
    342342
    any plot that is created. Sphinx-gallery will provide the correct reference
    343343
    when the documentation is built.
    344344

    345+
    Tools for writing mathematical expressions
    346+
    ------------------------------------------
    347+
    348+
    In most cases, you will likely want to use one of `Sphinx's builtin Math
    349+
    extensions <https://www.sphinx-doc.org/en/master/usage/extensions/math.html>`__.
    350+
    In rare cases we want the rendering of the mathematical text in the
    351+
    documentation html to exactly match with the rendering of the mathematical
    352+
    expression in the Matplotlib figure. In these cases, you can use the
    353+
    `matplotlib.sphinxext.mathmpl` Sphinx extension (See also the
    354+
    :doc:`../users/explain/text/mathtext` tutorial.)
    345355

    346356
    .. _writing-docstrings:
    347357

    ‎galleries/users_explain/text/mathtext.py

    Lines changed: 5 additions & 0 deletions
    Original file line numberDiff line numberDiff line change
    @@ -57,6 +57,11 @@
    5757
    characters will behave differently depending on :rc:`text.usetex`. See the
    5858
    :ref:`usetex tutorial <usetex>` for more information.
    5959
    60+
    .. note::
    61+
    To generate html output in documentation that will exactly match the output
    62+
    generated by ``mathtext``, use the `matplotlib.sphinxext.mathmpl` Sphinx
    63+
    extension.
    64+
    6065
    Subscripts and superscripts
    6166
    ---------------------------
    6267
    To make subscripts and superscripts, use the ``'_'`` and ``'^'`` symbols::

    ‎lib/matplotlib/sphinxext/mathmpl.py

    Lines changed: 8 additions & 1 deletion
    Original file line numberDiff line numberDiff line change
    @@ -2,11 +2,18 @@
    22
    A role and directive to display mathtext in Sphinx
    33
    ==================================================
    44
    5+
    The ``mathmpl`` Sphinx extension creates a mathtext image in Matplotlib and
    6+
    shows it in html output. Thus, it is a true and faithful representation of what
    7+
    you will see if you pass a given LaTeX string to Matplotlib (see
    8+
    :ref:`mathtext`).
    9+
    510
    .. warning::
    611
    In most cases, you will likely want to use one of `Sphinx's builtin Math
    712
    extensions
    813
    <https://www.sphinx-doc.org/en/master/usage/extensions/math.html>`__
    9-
    instead of this one.
    14+
    instead of this one. The builtin Sphinx math directive uses MathJax to
    15+
    render mathematical expressions, and addresses accessibility concerns that
    16+
    ``mathmpl`` doesn't address.
    1017
    1118
    Mathtext may be included in two ways:
    1219

    0 commit comments

    Comments
     (0)
    0