From cf4e8122a2dc3e10932e8bd4d2db61ef0f87c0f2 Mon Sep 17 00:00:00 2001
From: hannah <story645@gmail.com>
Date: Tue, 24 Sep 2024 18:28:13 -0400
Subject: [PATCH 1/2] doc: add pandas and xarray fixtures to testing API docs

---
 doc/api/testing_api.rst | 7 +++++++
 doc/conf.py             | 1 +
 2 files changed, 8 insertions(+)

diff --git a/doc/api/testing_api.rst b/doc/api/testing_api.rst
index 7731d4510b27..8ea8b2cdb110 100644
--- a/doc/api/testing_api.rst
+++ b/doc/api/testing_api.rst
@@ -37,3 +37,10 @@
    :members:
    :undoc-members:
    :show-inheritance:
+
+
+Data container testing fixtures
+==================================
+
+.. autofunction:: matplotlib.testing.conftest.pd
+.. autofunction:: matplotlib.testing.conftest.xr
diff --git a/doc/conf.py b/doc/conf.py
index ea6b1a3fa444..c9d498e939f7 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -220,6 +220,7 @@ def tutorials_download_error(record):
 
 autosummary_generate = True
 autodoc_typehints = "none"
+autodoc_mock_imports = ["pytest"]
 
 # we should ignore warnings coming from importing deprecated modules for
 # autodoc purposes, as this will disappear automatically when they are removed

From dc3bdf54c97b591eb8ac50f00853e57fa82e3abe Mon Sep 17 00:00:00 2001
From: hannah <story645@gmail.com>
Date: Wed, 25 Sep 2024 13:52:39 -0400
Subject: [PATCH 2/2] Update doc/api/testing_api.rst

Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
---
 doc/api/testing_api.rst            |  3 ++-
 lib/matplotlib/testing/conftest.py | 31 ++++++++++++++++++++++++++++--
 2 files changed, 31 insertions(+), 3 deletions(-)

diff --git a/doc/api/testing_api.rst b/doc/api/testing_api.rst
index 8ea8b2cdb110..ae81d2f89ca7 100644
--- a/doc/api/testing_api.rst
+++ b/doc/api/testing_api.rst
@@ -39,8 +39,9 @@
    :show-inheritance:
 
 
-Data container testing fixtures
+Testing with optional dependencies
 ==================================
+For more information on fixtures, see :external+pytest:ref:`pytest fixtures <about-fixtures>`.
 
 .. autofunction:: matplotlib.testing.conftest.pd
 .. autofunction:: matplotlib.testing.conftest.xr
diff --git a/lib/matplotlib/testing/conftest.py b/lib/matplotlib/testing/conftest.py
index c285c247e7b4..3f96de611195 100644
--- a/lib/matplotlib/testing/conftest.py
+++ b/lib/matplotlib/testing/conftest.py
@@ -82,7 +82,20 @@ def mpl_test_settings(request):
 
 @pytest.fixture
 def pd():
-    """Fixture to import and configure pandas."""
+    """
+    Fixture to import and configure pandas. Using this fixture, the test is skipped when
+    pandas is not installed. Use this fixture instead of importing pandas in test files.
+
+    Examples
+    --------
+    Request the pandas fixture by passing in ``pd`` as an argument to the test ::
+
+        def test_matshow_pandas(pd):
+
+            df = pd.DataFrame({'x':[1,2,3], 'y':[4,5,6]})
+            im = plt.figure().subplots().matshow(df)
+            np.testing.assert_array_equal(im.get_array(), df)
+    """
     pd = pytest.importorskip('pandas')
     try:
         from pandas.plotting import (
@@ -95,6 +108,20 @@ def pd():
 
 @pytest.fixture
 def xr():
-    """Fixture to import xarray."""
+    """
+    Fixture to import xarray so that the test is skipped when xarray is not installed.
+    Use this fixture instead of importing xrray in test files.
+
+    Examples
+    --------
+    Request the xarray fixture by passing in ``xr`` as an argument to the test ::
+
+        def test_imshow_xarray(xr):
+
+            ds = xr.DataArray(np.random.randn(2, 3))
+            im = plt.figure().subplots().imshow(ds)
+            np.testing.assert_array_equal(im.get_array(), ds)
+    """
+
     xr = pytest.importorskip('xarray')
     return xr