matplotlib · timhoffm · Sep 15, 2023 · Sep 11, 2023 · Sep 15, 2023 · Sep 15, 2023
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -26,7 +26,6 @@ repos:
       - id: no-commit-to-branch #default is master and main
       - id: trailing-whitespace
         exclude_types: [svg]
-
   - repo: https://github.com/pycqa/flake8
     rev: 6.0.0
     hooks:
@@ -44,10 +43,15 @@ repos:
           "--skip",
           "doc/users/project/credits.rst"
           ]
-
   - repo: https://github.com/pycqa/isort
     rev: 5.12.0
     hooks:
       - id: isort
         name: isort (python)
         files: ^galleries/tutorials/|^galleries/examples/|^galleries/plot_types/
+  - repo: https://github.com/rstcheck/rstcheck
+    rev: v6.2.0
+    hooks:
+      - id: rstcheck
+        additional_dependencies:
+          - sphinx>=1.8.1
diff --git a/doc/_templates/autofunctions.rst b/doc/_templates/autofunctions.rst
@@ -14,7 +14,9 @@ Functions
 .. autosummary::
    :template: autosummary.rst
    :toctree:
+
 {% for item in functions %}{% if item not in ['plotting', 'colormaps'] %}
    {{ item }}{% endif %}{% endfor %}
+
 {% endif %}
 {% endblock %}
diff --git a/doc/_templates/automodule.rst b/doc/_templates/automodule.rst
@@ -1,8 +1,10 @@
 {{ fullname | escape | underline}}
 
 {% if fullname in ['mpl_toolkits.axes_grid1.colorbar'] %}
-.. To prevent problems with the autosummary for the colorbar doc
-   treat this separately (sphinx-doc/sphinx/issues/4874)
+
+.. To prevent problems with the autosummary for the colorbar doc treat this
+   separately (sphinx-doc/sphinx/issues/4874)
+
 .. automodule:: {{ fullname }}
    :members:
 
@@ -21,8 +23,10 @@ Classes
 .. autosummary::
    :template: autosummary.rst
    :toctree:
+
 {% for item in classes %}{% if item not in ['zip', 'map', 'reduce'] %}
    {{ item }}{% endif %}{% endfor %}
+
 {% endif %}
 {% endblock %}
 
@@ -38,6 +42,7 @@ Functions
 
 {% for item in functions %}{% if item not in ['zip', 'map', 'reduce'] %}
    {{ item }}{% endif %}{% endfor %}
+
 {% endif %}
 {% endblock %}
 {% endif %}
diff --git a/doc/_templates/autosummary.rst b/doc/_templates/autosummary.rst
@@ -5,6 +5,7 @@
 
 
 {% if objtype in ['class'] %}
+
 .. auto{{ objtype }}:: {{ objname }}
     :show-inheritance:
     :special-members: __call__
@@ -16,11 +17,13 @@
 
 {% if objtype in ['class', 'method', 'function'] %}
 {% if objname in ['AxesGrid', 'Scalable', 'HostAxes', 'FloatingAxes',
-                      'ParasiteAxesAuxTrans', 'ParasiteAxes'] %}
+'ParasiteAxesAuxTrans', 'ParasiteAxes'] %}
+
 .. Filter out the above aliases to other classes, as sphinx gallery
    creates no example file for those (sphinx-gallery/sphinx-gallery#365)
 
 {% else %}
+
 .. minigallery:: {{module}}.{{objname}}
    :add-heading:
 

diff --git a/doc/_templates/autosummary_class_only.rst b/doc/_templates/autosummary_class_only.rst
@@ -5,6 +5,7 @@
 
 
 {% if objtype in ['class'] %}
+
 .. auto{{ objtype }}:: {{ objname }}
     :no-members:
 

diff --git a/doc/api/next_api_changes/behavior/25775-HZ.rst b/doc/api/next_api_changes/behavior/25775-HZ.rst
@@ -4,7 +4,7 @@ Default antialiasing behavior changes for ``Text`` and ``Annotation``
 ``matplotlib.pyplot.annotate()`` and ``matplotlib.pyplot.text()`` now support parameter *antialiased* when initializing.
 Examples:
 
-.. code-block::
+.. code-block:: python
 
     mpl.text.Text(.5, .5, "foo\nbar", antialiased=True)
     plt.text(0.5, 0.5, '6 inches x 2 inches', antialiased=True)

diff --git a/doc/api/prev_api_changes/api_changes_2.1.2.rst b/doc/api/prev_api_changes/api_changes_2.1.2.rst
@@ -12,9 +12,9 @@ list of conditions was incomplete, didn't handle RGB tuples,
 didn't handle linewidths or linestyles etc.
 
 This logic did not exist in `.axes.Axes.legend`.  It was included (erroneously)
-in Matplotlib 2.1.1 when the legend argument parsing was unified
-[#9324](https://github.com/matplotlib/matplotlib/pull/9324).  This change
-removes that check in `.axes.Axes.legend` again to restore the old behavior.
+in Matplotlib 2.1.1 when the legend argument parsing was unified :ghpull:`9324`.  
+This change removes that check in `.axes.Axes.legend` again to restore the old 
+behavior.
 
 This logic has also been dropped from `.Figure.legend`, where it
 was previously undocumented. Repeated

diff --git a/doc/api/prev_api_changes/api_changes_3.5.0/behaviour.rst b/doc/api/prev_api_changes/api_changes_3.5.0/behaviour.rst
@@ -132,7 +132,7 @@ consistently exposes all the attributes and methods related to the line marker
 (:ghissue:`11358`). This makes it easy to change the marker features after
 instantiating a legend.
 
-.. code::
+.. code-block:: python
 
     import matplotlib.pyplot as plt
 
@@ -147,7 +147,7 @@ instantiating a legend.
 The former legend handler for Line2D objects has been renamed
 `.HandlerLine2DCompound`. To revert to the previous behaviour, one can use
 
-.. code::
+.. code-block:: python
 
     import matplotlib.legend as mlegend
     from matplotlib.legend_handler import HandlerLine2DCompound

diff --git a/doc/api/prev_api_changes/api_changes_3.7.0/behaviour.rst b/doc/api/prev_api_changes/api_changes_3.7.0/behaviour.rst
@@ -51,7 +51,7 @@ Now, the halfrange remains fixed when vcenter is changed, and **vmin** and
 
 For example, this is what the values were when changing vcenter previously.
 
-.. code-block::
+.. code-block:: python
 
     norm = CenteredNorm(vcenter=0, halfrange=1)
     # Move vcenter up by one
@@ -61,7 +61,7 @@ For example, this is what the values were when changing vcenter previously.
 
 and now, with that same example
 
-.. code-block::
+.. code-block:: python
 
     norm = CenteredNorm(vcenter=0, halfrange=1)
     norm.vcenter = 1

diff --git a/doc/devel/MEP/MEP23.rst b/doc/devel/MEP/MEP23.rst
@@ -34,8 +34,8 @@ This is and may continue to be the desired method of operation for
 most use cases.
 
 Sometimes when there are too many figures open at the same time, it is
-desirable to be able to group these under the same window
-[see](https://github.com/matplotlib/matplotlib/issues/2194).
+desirable to be able to group these under the same window. See :ghpull:`2194`.
+
 
 The proposed solution modifies `.FigureManagerBase` to contain and manage more
 than one ``Canvas``. The settings parameter :rc:`backend.multifigure` control
@@ -44,7 +44,7 @@ when the **MultiFigure** behaviour is desired.
 **Note**
 
 It is important to note, that the proposed solution, assumes that the
-[MEP22](https://github.com/matplotlib/matplotlib/wiki/Mep22) is
+`MEP22 <https://github.com/matplotlib/matplotlib/wiki/Mep22>`_. is
 already in place. This is simply because the actual implementation of
 the ``Toolbar`` makes it pretty hard to switch between canvases.
 

diff --git a/doc/devel/MEP/MEP28.rst b/doc/devel/MEP/MEP28.rst
@@ -264,6 +264,7 @@ value of ``statfxn`` would be ``cbook.boxplot_stats``, but users could
 pass their own function. Then ``transform_in`` and ``transform_out`` would
 then be passed as elements of the ``statfxn_args`` parameter.
 
+.. rstcheck: ignore-next-code-block
 .. code:: python
 
    def boxplot_stats(data, ..., transform_in=None, transform_out=None):

diff --git a/doc/devel/contribute.rst b/doc/devel/contribute.rst
@@ -170,18 +170,18 @@ also welcome to post feature requests or pull requests.
 
 If you are reporting a bug, please do your best to include the following:
 
-1. A short, top-level summary of the bug. In most cases, this should be 1-2
+#. A short, top-level summary of the bug. In most cases, this should be 1-2
    sentences.
 
-2. A short, self-contained code snippet to reproduce the bug, ideally allowing
+#. A short, self-contained code snippet to reproduce the bug, ideally allowing
    a simple copy and paste to reproduce. Please do your best to reduce the code
    snippet to the minimum required.
 
-3. The actual outcome of the code snippet.
+#. The actual outcome of the code snippet.
 
-4. The expected outcome of the code snippet.
+#. The expected outcome of the code snippet.
 
-5. The Matplotlib version, Python version and platform that you are using. You
+#. The Matplotlib version, Python version and platform that you are using. You
    can grab the version with the following commands::
 
       >>> import matplotlib
@@ -229,52 +229,54 @@ contribute to Matplotlib.
 
 A brief overview of the workflow is as follows.
 
-1. `Create an account <https://github.com/join>`_ on GitHub if you do not
+#. `Create an account <https://github.com/join>`_ on GitHub if you do not
    already have one.
 
-2. Fork the `project repository <https://github.com/matplotlib/matplotlib>`_:
-   click on the 'Fork' button near the top of the page. This creates a copy of
-   the code under your account on the GitHub server.
+#. Fork the `project repository <https://github.com/matplotlib/matplotlib>`_ by
+   clicking on the :octicon:`repo-forked` **Fork** button near the top of the page.
+   This creates a copy of the code under your account on the GitHub server.
 
-.. tab-set::
+#. Set up a development environment:
 
-    .. tab-item:: Local development
+   .. tab-set::
 
-        3. Clone this copy to your local disk::
+      .. tab-item:: Local development
 
-             git clone https://github.com/<YOUR GITHUB USERNAME>/matplotlib.git
+          Clone this copy to your local disk::
 
-    .. tab-item:: Using GitHub Codespaces
+            git clone https://github.com/<YOUR GITHUB USERNAME>/matplotlib.git
 
-        3. Check out the Matplotlib repository and activate your development
-           environment:
+      .. tab-item:: Using GitHub Codespaces
 
-           * Open codespaces on your fork by clicking on the green "Code" button
+          Check out the Matplotlib repository and activate your development environment:
+
+          #. Open codespaces on your fork by clicking on the green "Code" button
              on the GitHub web interface and selecting the "Codespaces" tab.
-           * Next, click on "Open codespaces on <your branch name>". You will be
+
+          #. Next, click on "Open codespaces on <your branch name>". You will be
              able to change branches later, so you can select the default
              ``main`` branch.
-           * After the codespace is created, you will be taken to a new browser
+
+          #. After the codespace is created, you will be taken to a new browser
              tab where you can use the terminal to activate a pre-defined conda
              environment called ``mpl-dev``::
 
-               conda activate mpl-dev
-
+              conda activate mpl-dev
 
 
-4. Install the local version of Matplotlib with::
+#. Install the local version of Matplotlib with::
 
      python -m pip install -e .
 
    See :ref:`installing_for_devs` for detailed instructions.
 
-5. Create a branch to hold your changes::
+#. Create a branch to hold your changes::
 
      git checkout -b my-feature origin/main
 
    and start making changes. Never work in the ``main`` branch!
 
-6. Work on this task using Git to do the version control. Codespaces persist for
+#. Work on this task using Git to do the version control. Codespaces persist for
    some time (check the `documentation for details
    <https://docs.github.com/codespaces/getting-started/the-codespace-lifecycle>`_)
    and can be managed on https://github.com/codespaces. When you're done editing
@@ -301,11 +303,11 @@ GitHub Codespaces workflows
   <https://github.com/devcontainers/features/tree/main/src/desktop-lite>`_.
   You can use it by connecting to this desktop via your web browser. To do this:
 
-  1. Press ``F1`` or ``Ctrl/Cmd+Shift+P`` and select
+  #. Press ``F1`` or ``Ctrl/Cmd+Shift+P`` and select
      ``Ports: Focus on Ports View`` in the VSCode session to bring it into
      focus. Open the ports view in your tool, select the ``noVNC`` port, and
      click the Globe icon.
-  2. In the browser that appears, click the Connect button and enter the desktop
+  #. In the browser that appears, click the Connect button and enter the desktop
      password (``vscode`` by default).
 
   Check the `GitHub instructions
@@ -391,10 +393,11 @@ Rules
 Introducing
 ~~~~~~~~~~~
 
-1. Announce the deprecation in a new file
+#. Announce the deprecation in a new file
    :file:`doc/api/next_api_changes/deprecations/99999-ABC.rst` where ``99999``
    is the pull request number and ``ABC`` are the contributor's initials.
-2. If possible, issue a `~matplotlib.MatplotlibDeprecationWarning` when the
+
+#. If possible, issue a `~matplotlib.MatplotlibDeprecationWarning` when the
    deprecated API is used. There are a number of helper tools for this:
 
    - Use ``_api.warn_deprecated()`` for general deprecation warnings
@@ -411,7 +414,7 @@ Introducing
 
    You can use standard rst cross references in *alternative*.
 
-3. Make appropriate changes to the type hints in the associated ``.pyi`` file.
+#. Make appropriate changes to the type hints in the associated ``.pyi`` file.
    The general guideline is to match runtime reported behavior.
 
    - Items marked with ``@_api.deprecated`` or ``@_api.deprecate_privatize_attribute``
@@ -431,15 +434,17 @@ Introducing
 Expiring
 ~~~~~~~~
 
-1. Announce the API changes in a new file
+#. Announce the API changes in a new file
    :file:`doc/api/next_api_changes/[kind]/99999-ABC.rst` where ``99999``
    is the pull request number and ``ABC`` are the contributor's initials, and
    ``[kind]`` is one of the folders :file:`behavior`, :file:`development`,
    :file:`removals`. See :file:`doc/api/next_api_changes/README.rst` for more
    information. For the content, you can usually copy the deprecation notice
    and adapt it slightly.
-2. Change the code functionality and remove any related deprecation warnings.
-3. Make appropriate changes to the type hints in the associated ``.pyi`` file.
+
+#. Change the code functionality and remove any related deprecation warnings.
+
+#. Make appropriate changes to the type hints in the associated ``.pyi`` file.
 
    - Items marked with ``@_api.deprecated`` or ``@_api.deprecate_privatize_attribute``
      are to be removed on expiry.

diff --git a/doc/devel/document.rst b/doc/devel/document.rst
@@ -668,7 +668,7 @@ in that case, they can be documented as an ``.. ACCEPTS:`` block, e.g. for
 
 .. code-block:: python
 
-   def set_xlim(self, ...):
+   def set_xlim(self, left=None, right=None):
        """
        Set the x-axis view limits.
 

diff --git a/doc/users/next_whats_new/antialiasing_text_annotation.rst b/doc/users/next_whats_new/antialiasing_text_annotation.rst
@@ -6,7 +6,7 @@ When *antialiased* is set to ``False``, antialiasing will not be applied to the
 When *antialiased* is not specified, antialiasing will be set by :rc:`text.antialiased` at the creation time of ``Text`` and ``Annotation`` object.
 Examples:
 
-.. code-block::
+.. code-block:: python
 
     mpl.text.Text(.5, .5, "foo\nbar", antialiased=True)
     plt.text(0.5, 0.5, '6 inches x 2 inches', antialiased=True)
@@ -15,7 +15,7 @@ Examples:
 If the text contains math expression, *antialiased* applies to the whole text.
 Examples:
 
-.. code-block::
+.. code-block:: python
 
     # no part will be antialiased for the text below
     plt.text(0.5, 0.25, r"$I'm \sqrt{x}$", antialiased=False)

diff --git a/doc/users/next_whats_new/boldsym_mathtext.rst b/doc/users/next_whats_new/boldsym_mathtext.rst
@@ -6,7 +6,7 @@ Supports using the ``\boldsymbol{}`` command in mathtext:
 To change symbols to bold enclose the text in a font command as
 shown:
 
-.. code-block::
+.. code-block:: none
 
     r'$\boldsymbol{a+2+\alpha}$'
 

diff --git a/doc/users/next_whats_new/mathtext_features.rst b/doc/users/next_whats_new/mathtext_features.rst
@@ -5,7 +5,7 @@
 
 To use it to enclose the math in a substack command as shown:
 
-.. code-block::
+.. code-block:: none
 
     r'$\sum_{\substack{1\leq i\leq 3\\ 1\leq j\leq 5}}$'
 
@@ -23,7 +23,7 @@ The ``\middle`` delimiter has been added, and can now be used with the
 To use the middle command enclose it in between the ``\left`` and
 ``\right`` delimiter command as shown:
 
-.. code-block::
+.. code-block:: none
 
     r'$\left( \frac{a}{b} \middle| q \right)$'
Original file line number	Diff line number	Diff line change
		@@ -5,6 +5,7 @@


		{% if objtype in ['class'] %}

		.. auto{{ objtype }}:: {{ objname }}
		:no-members: