Add matplotlib.testing to the documentation

timhoffm · timhoffm · commit 420d56662cd3 · 2018-10-28T22:10:17.000+01:00
diff --git a/doc/api/index.rst b/doc/api/index.rst
@@ -54,6 +54,7 @@ Modules
    spines_api.rst
    style_api.rst
    table_api.rst
+   testing_api.rst
    text_api.rst
    ticker_api.rst
    tight_layout_api.rst
diff --git a/doc/api/testing_api.rst b/doc/api/testing_api.rst
@@ -0,0 +1,48 @@
+*******
+testing
+*******
+
+
+:mod:`matplotlib.testing`
+=========================
+
+.. automodule:: matplotlib.testing
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+:mod:`matplotlib.testing.compare`
+=================================
+
+.. automodule:: matplotlib.testing.compare
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+:mod:`matplotlib.testing.decorators`
+====================================
+
+.. automodule:: matplotlib.testing.decorators
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+:mod:`matplotlib.testing.disable_internet`
+==========================================
+
+.. automodule:: matplotlib.testing.disable_internet
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+:mod:`matplotlib.testing.exceptions`
+====================================
+
+.. automodule:: matplotlib.testing.exceptions
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/lib/matplotlib/testing/__init__.py b/lib/matplotlib/testing/__init__.py
@@ -1,3 +1,6 @@
+"""
+Helper functions for testing.
+"""
 import locale
 import warnings
 
@@ -6,7 +9,7 @@
 
 
 def is_called_from_pytest():
-    """Returns whether the call was done from pytest"""
+    """Whether we are in a pytest run."""
     return getattr(mpl, '_called_from_pytest', False)
 
 
diff --git a/lib/matplotlib/testing/compare.py b/lib/matplotlib/testing/compare.py
@@ -281,9 +281,14 @@ def _update_converter():
 
 def comparable_formats():
     """
-    Returns the list of file formats that compare_images can compare
+    Return the list of file formats that `.compare_images` can compare
     on this system.
 
+    Returns
+    -------
+    supported_formats : list of str
+        E.g. ``['png', 'pdf', 'svg', 'eps']``.
+
     """
     return ['png', *converter]
 
@@ -369,21 +374,41 @@ def compare_images(expected, actual, tol, in_decorator=False):
     ----------
     expected : str
         The filename of the expected image.
-    actual :str
+    actual : str
         The filename of the actual image.
     tol : float
         The tolerance (a color value difference, where 255 is the
         maximal difference).  The test fails if the average pixel
         difference is greater than this value.
     in_decorator : bool
-        If called from image_comparison decorator, this should be
-        True. (default=False)
+        Determines the output format. If called from image_comparison
+        decorator, this should be True. (default=False)
+
+    Returns
+    -------
+    comparison_result : None or dict or str
+        Return *None* if the images are equal within the given tolerance.
+
+        If the images differ, the return value depends on  *in_decorator*.
+        If *in_decorator* is true, a dict with the following entries is
+        returned:
+
+        - *rms*: The RMS of the image difference.
+        - *expected*: The filename of the expected image.
+        - *actual*: The filename of the actual image.
+        - *diff_image*: The filename of the difference image.
+        - *tol*: The comparison tolerance.
+
+        Otherwise, a human-readable multi-line string representation of this
+        information is returned.
 
     Examples
     --------
-    img1 = "./baseline/plot.png"
-    img2 = "./output/plot.png"
-    compare_images(img1, img2, 0.001):
+    ::
+
+        img1 = "./baseline/plot.png"
+        img2 = "./output/plot.png"
+        compare_images(img1, img2, 0.001)
 
     """
     if not os.path.exists(actual):
