doc: add pandas and xarray fixtures to testing API docs (#28879)

story645 · timhoffm · web-flow · commit ba05b4484aac · 2024-09-26T17:14:09.000+02:00
Co-authored-by: Tim Hoffmann &lt;2836374+timhoffm@users.noreply.github.com&gt;
diff --git a/doc/api/testing_api.rst b/doc/api/testing_api.rst
@@ -37,3 +37,11 @@
    :members:
    :undoc-members:
    :show-inheritance:
+
+
+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/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
diff --git 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
