Merge pull request #18905 from brunobeltran/fail-docs-on-warn

tacaswell · web-flow · commit e547e703b7b3 · 2020-11-09T15:10:26.000-05:00
DOC: Make docs fail on Warning (and fix all existing warnings)
diff --git a/doc/conf.py b/doc/conf.py
@@ -30,6 +30,11 @@
 # General configuration
 # ---------------------
 
+# Unless we catch the warning explicitly somewhere, a warning should cause the
+# docs build to fail. This is especially useful for getting rid of deprecated
+# usage in the gallery.
+warnings.filterwarnings('error', append=True)
+
 # Strip backslahes in function's signature
 # To be removed when numpydoc > 0.9.x
 strip_signature_backslash = True
@@ -108,6 +113,12 @@ def _check_dependencies():
 
 autosummary_generate = True
 
+# we should ignore warnings coming from importing deprecated modules for
+# autodoc purposes, as this will disappear automatically when they are removed
+warnings.filterwarnings('ignore', category=MatplotlibDeprecationWarning,
+                        module='importlib',  # used by sphinx.autodoc.importer
+                        message=r'(\n|.)*module was deprecated.*')
+
 autodoc_docstring_signature = True
 autodoc_default_options = {'members': None, 'undoc-members': None}
 
diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
@@ -91,6 +91,7 @@ Optional, but recommended:
 *  `optipng <http://optipng.sourceforge.net>`_
 *  the font "Humor Sans" (aka the "XKCD" font), or the free alternative
    `Comic Neue <http://comicneue.com/>`_.
+*  the font "Times New Roman"
 
 .. note::
 
diff --git a/examples/animation/rain.py b/examples/animation/rain.py
@@ -25,10 +25,10 @@
 
 # Create rain data
 n_drops = 50
-rain_drops = np.zeros(n_drops, dtype=[('position', float, 2),
-                                      ('size',     float, 1),
-                                      ('growth',   float, 1),
-                                      ('color',    float, 4)])
+rain_drops = np.zeros(n_drops, dtype=[('position', float, (2,)),
+                                      ('size',     float),
+                                      ('growth',   float),
+                                      ('color',    float, (4,))])
 
 # Initialize the raindrops in random positions and with
 # random growth rates.
diff --git a/examples/images_contours_and_fields/contourf_demo.py b/examples/images_contours_and_fields/contourf_demo.py
@@ -5,7 +5,6 @@
 
 How to use the `.axes.Axes.contourf` method to create filled contour plots.
 """
-
 import numpy as np
 import matplotlib.pyplot as plt
 
@@ -88,8 +87,7 @@
 # Illustrate all 4 possible "extend" settings:
 extends = ["neither", "both", "min", "max"]
 cmap = plt.cm.get_cmap("winter")
-cmap.set_under("magenta")
-cmap.set_over("yellow")
+cmap = cmap.with_extremes(under="magenta", over="yellow")
 # Note: contouring simply excludes masked or nan regions, so
 # instead of using the "bad" colormap value for them, it draws
 # nothing at all in them.  Therefore the following would have
diff --git a/examples/images_contours_and_fields/pcolormesh_grids.py b/examples/images_contours_and_fields/pcolormesh_grids.py
@@ -55,15 +55,16 @@ def _annotate(ax, x, y, title):
 # -----------------------------
 #
 # Often, however, data is provided where *X* and *Y* match the shape of *Z*.
-# As of Matplotlib v3.3, ``shading='flat'`` is deprecated when this is the
-# case, a warning is raised, and the last row and column of *Z* are dropped.
-# This dropping of the last row and column is what Matplotlib did silently
-# previous to v3.3, and is compatible with what Matlab does.
+# While this makes sense for other ``shading`` types, it is no longer permitted
+# when ``shading='flat'`` (and will raise a MatplotlibDeprecationWarning as of
+# Matplotlib v3.3). Historically, Matplotlib silently dropped the last row and
+# column of *Z* in this case, to match Matlab's behavior. If this behavior is
+# still desired, simply drop the last row and column manually:
 
 x = np.arange(ncols)  # note *not* ncols + 1 as before
 y = np.arange(nrows)
 fig, ax = plt.subplots()
-ax.pcolormesh(x, y, Z, shading='flat', vmin=Z.min(), vmax=Z.max())
+ax.pcolormesh(x, y, Z[:-1, :-1], shading='flat', vmin=Z.min(), vmax=Z.max())
 _annotate(ax, x, y, "shading='flat': X, Y, C same shape")
 
 ###############################################################################
diff --git a/examples/images_contours_and_fields/pcolormesh_levels.py b/examples/images_contours_and_fields/pcolormesh_levels.py
@@ -51,11 +51,12 @@
 # ---------------------
 #
 # Often a user wants to pass *X* and *Y* with the same sizes as *Z* to
-# `.axes.Axes.pcolormesh`.  This is also allowed if ``shading='auto'`` is
-# passed (default set by :rc:`pcolor.shading`).  Pre Matplotlib 3.3,
+# `.axes.Axes.pcolormesh`. This is also allowed if ``shading='auto'`` is
+# passed (default set by :rc:`pcolor.shading`). Pre Matplotlib 3.3,
 # ``shading='flat'`` would drop the last column and row of *Z*; while that
 # is still allowed for back compatibility purposes, a DeprecationWarning is
-# raised.
+# raised. If this is really what you want, then simply drop the last row and
+# column of Z manually:
 
 x = np.arange(10)  # len = 10
 y = np.arange(6)  # len = 6
@@ -64,7 +65,8 @@
 fig, axs = plt.subplots(2, 1, sharex=True, sharey=True)
 axs[0].pcolormesh(X, Y, Z, vmin=np.min(Z), vmax=np.max(Z), shading='auto')
 axs[0].set_title("shading='auto' = 'nearest'")
-axs[1].pcolormesh(X, Y, Z, vmin=np.min(Z), vmax=np.max(Z), shading='flat')
+axs[1].pcolormesh(X, Y, Z[:-1, :-1], vmin=np.min(Z), vmax=np.max(Z),
+                  shading='flat')
 axs[1].set_title("shading='flat'")
 
 ###############################################################################
diff --git a/examples/specialty_plots/advanced_hillshading.py b/examples/specialty_plots/advanced_hillshading.py
@@ -25,7 +25,7 @@ def display_colorbar():
     # Use a proxy artist for the colorbar...
     im = ax.imshow(z, cmap=cmap)
     im.remove()
-    fig.colorbar(im)
+    fig.colorbar(im, ax=ax)
 
     ax.set_title('Using a colorbar with a shaded plot', size='x-large')
 
diff --git a/examples/style_sheets/style_sheets_reference.py b/examples/style_sheets/style_sheets_reference.py
@@ -137,7 +137,8 @@ def plot_figure(style_label=""):
 
     # Plot a demonstration figure for every available style sheet.
     for style_label in style_list:
-        with plt.style.context(style_label):
-            fig = plot_figure(style_label=style_label)
+        with plt.rc_context({"figure.max_open_warning": len(style_list)}):
+            with plt.style.context(style_label):
+                fig = plot_figure(style_label=style_label)
 
     plt.show()
diff --git a/examples/subplots_axes_and_figures/secondary_axis.py b/examples/subplots_axes_and_figures/secondary_axis.py
@@ -57,15 +57,20 @@ def rad2deg(x):
 ax.set_title('Random spectrum')
 
 
-def forward(x):
-    return 1 / x
+def one_over(x):
+    """Vectorized 1/x, treating x==0 manually"""
+    x = np.array(x).astype(float)
+    near_zero = np.isclose(x, 0)
+    x[near_zero] = np.inf
+    x[~near_zero] = 1 / x[~near_zero]
+    return x
 
 
-def inverse(x):
-    return 1 / x
+# the function "1/x" is its own inverse
+inverse = one_over
 
 
-secax = ax.secondary_xaxis('top', functions=(forward, inverse))
+secax = ax.secondary_xaxis('top', functions=(one_over, inverse))
 secax.set_xlabel('period [s]')
 plt.show()
 
diff --git a/examples/text_labels_and_annotations/usetex_baseline_test.py b/examples/text_labels_and_annotations/usetex_baseline_test.py
@@ -30,8 +30,10 @@ def __init__(self, *args, preview=False, **kwargs):
         super().__init__(*args, **kwargs)
 
     def draw(self, renderer):
-        with plt.rc_context({"text.latex.preview": self.preview}):
-            super().draw(renderer)
+        from matplotlib import _api  # internal, *do not use*
+        with _api.suppress_matplotlib_deprecation_warning():
+            with plt.rc_context({"text.latex.preview": self.preview}):
+                super().draw(renderer)
 
 
 def test_window_extent(ax, usetex, preview):
diff --git a/examples/ticks_and_spines/date_precision_and_epochs.py b/examples/ticks_and_spines/date_precision_and_epochs.py
@@ -113,25 +113,30 @@ def _reset_epoch_for_tutorial():
 # --------
 #
 # This all of course has an effect on plotting.  With the old default epoch
-# the times were rounded, leading to jumps in the data:
+# the times were rounded during the internal ``date2num`` conversion, leading
+# to jumps in the data:
 
 _reset_epoch_for_tutorial()  # Don't do this.  Just for this tutorial.
 mdates.set_epoch(old_epoch)
 
 x = np.arange('2000-01-01T00:00:00.0', '2000-01-01T00:00:00.000100',
               dtype='datetime64[us]')
+# simulate the plot being made using the old epoch
+xold = np.array([mdates.num2date(mdates.date2num(d)) for d in x])
 y = np.arange(0, len(x))
+
+# resetting the Epoch so plots are comparable
+_reset_epoch_for_tutorial()  # Don't do this.  Just for this tutorial.
+mdates.set_epoch(new_epoch)
+
 fig, ax = plt.subplots(constrained_layout=True)
-ax.plot(x, y)
+ax.plot(xold, y)
 ax.set_title('Epoch: ' + mdates.get_epoch())
 plt.setp(ax.xaxis.get_majorticklabels(), rotation=40)
 plt.show()
 
 #############################################################################
-# For a more recent epoch, the plot is smooth:
-
-_reset_epoch_for_tutorial()  # Don't do this.  Just for this tutorial.
-mdates.set_epoch(new_epoch)
+# For dates plotted using the more recent epoch, the plot is smooth:
 
 fig, ax = plt.subplots(constrained_layout=True)
 ax.plot(x, y)
diff --git a/examples/userdemo/colormap_normalizations.py b/examples/userdemo/colormap_normalizations.py
@@ -29,10 +29,10 @@
 
 pcm = ax[0].pcolor(X, Y, Z,
                    norm=colors.LogNorm(vmin=Z.min(), vmax=Z.max()),
-                   cmap='PuBu_r')
+                   cmap='PuBu_r', shading='nearest')
 fig.colorbar(pcm, ax=ax[0], extend='max')
 
-pcm = ax[1].pcolor(X, Y, Z, cmap='PuBu_r')
+pcm = ax[1].pcolor(X, Y, Z, cmap='PuBu_r', shading='nearest')
 fig.colorbar(pcm, ax=ax[1], extend='max')
 
 
@@ -46,10 +46,10 @@
 fig, ax = plt.subplots(2, 1)
 
 pcm = ax[0].pcolormesh(X, Y, Z1, norm=colors.PowerNorm(gamma=1. / 2.),
-                       cmap='PuBu_r')
+                       cmap='PuBu_r', shading='nearest')
 fig.colorbar(pcm, ax=ax[0], extend='max')
 
-pcm = ax[1].pcolormesh(X, Y, Z1, cmap='PuBu_r')
+pcm = ax[1].pcolormesh(X, Y, Z1, cmap='PuBu_r', shading='nearest')
 fig.colorbar(pcm, ax=ax[1], extend='max')
 
 ###############################################################################
@@ -70,10 +70,11 @@
 pcm = ax[0].pcolormesh(X, Y, Z1,
                        norm=colors.SymLogNorm(linthresh=0.03, linscale=0.03,
                                               vmin=-1.0, vmax=1.0, base=10),
-                       cmap='RdBu_r')
+                       cmap='RdBu_r', shading='nearest')
 fig.colorbar(pcm, ax=ax[0], extend='both')
 
-pcm = ax[1].pcolormesh(X, Y, Z1, cmap='RdBu_r', vmin=-np.max(Z1))
+pcm = ax[1].pcolormesh(X, Y, Z1, cmap='RdBu_r', vmin=-np.max(Z1),
+                       shading='nearest')
 fig.colorbar(pcm, ax=ax[1], extend='both')
 
 
@@ -108,10 +109,11 @@ def __call__(self, value, clip=None):
 
 pcm = ax[0].pcolormesh(X, Y, Z,
                        norm=MidpointNormalize(midpoint=0.),
-                       cmap='RdBu_r')
+                       cmap='RdBu_r', shading='nearest')
 fig.colorbar(pcm, ax=ax[0], extend='both')
 
-pcm = ax[1].pcolormesh(X, Y, Z, cmap='RdBu_r', vmin=-np.max(Z))
+pcm = ax[1].pcolormesh(X, Y, Z, cmap='RdBu_r', vmin=-np.max(Z),
+                       shading='nearest')
 fig.colorbar(pcm, ax=ax[1], extend='both')
 
 ###############################################################################
@@ -126,16 +128,17 @@ def __call__(self, value, clip=None):
 norm = colors.BoundaryNorm(boundaries=bounds, ncolors=256)
 pcm = ax[0].pcolormesh(X, Y, Z,
                        norm=norm,
-                       cmap='RdBu_r')
+                       cmap='RdBu_r', shading='nearest')
 fig.colorbar(pcm, ax=ax[0], extend='both', orientation='vertical')
 
 # uneven bounds changes the colormapping:
 bounds = np.array([-0.25, -0.125, 0, 0.5, 1])
 norm = colors.BoundaryNorm(boundaries=bounds, ncolors=256)
-pcm = ax[1].pcolormesh(X, Y, Z, norm=norm, cmap='RdBu_r')
+pcm = ax[1].pcolormesh(X, Y, Z, norm=norm, cmap='RdBu_r', shading='nearest')
 fig.colorbar(pcm, ax=ax[1], extend='both', orientation='vertical')
 
-pcm = ax[2].pcolormesh(X, Y, Z, cmap='RdBu_r', vmin=-np.max(Z1))
+pcm = ax[2].pcolormesh(X, Y, Z, cmap='RdBu_r', vmin=-np.max(Z1),
+                       shading='nearest')
 fig.colorbar(pcm, ax=ax[2], extend='both', orientation='vertical')
 
 plt.show()
diff --git a/examples/userdemo/colormap_normalizations_symlognorm.py b/examples/userdemo/colormap_normalizations_symlognorm.py
@@ -30,10 +30,11 @@
 pcm = ax[0].pcolormesh(X, Y, Z,
                        norm=colors.SymLogNorm(linthresh=0.03, linscale=0.03,
                                               vmin=-1.0, vmax=1.0, base=10),
-                       cmap='RdBu_r')
+                       cmap='RdBu_r', shading='nearest')
 fig.colorbar(pcm, ax=ax[0], extend='both')
 
-pcm = ax[1].pcolormesh(X, Y, Z, cmap='RdBu_r', vmin=-np.max(Z))
+pcm = ax[1].pcolormesh(X, Y, Z, cmap='RdBu_r', vmin=-np.max(Z),
+                       shading='nearest')
 fig.colorbar(pcm, ax=ax[1], extend='both')
 
 plt.show()
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -524,8 +524,14 @@ def secondary_xaxis(self, location, *, functions=None, **kwargs):
             ax.set_xlabel('frequency [Hz]')
 
             def invert(x):
-                return 1 / x
-
+                # 1/x with special treatment of x == 0
+                x = np.array(x).astype(float)
+                near_zero = np.isclose(x, 0)
+                x[near_zero] = np.inf
+                x[~near_zero] = 1 / x[~near_zero]
+                return x
+
+            # the inverse of 1/x is itself
             secax = ax.secondary_xaxis('top', functions=(invert, invert))
             secax.set_xlabel('Period [s]')
             plt.show()
diff --git a/lib/matplotlib/cbook/deprecation.py b/lib/matplotlib/cbook/deprecation.py
@@ -3,5 +3,6 @@
     MatplotlibDeprecationWarning, mplDeprecation, warn_deprecated, deprecated)
 
 warn_deprecated("3.4",
-                "The module matplotlib.cbook.deprecation is considered "
-                "internal and it will be made private in the future.")
+                message="The module matplotlib.cbook.deprecation is "
+                "considered internal and it will be made private in the "
+                "future.")
diff --git a/tutorials/intermediate/tight_layout_guide.py b/tutorials/intermediate/tight_layout_guide.py
