Cleanup make_compound_path_from_poly doc, example.

Author: anntzer

examples/misc/histogram_path.py

@@ -4,29 +4,26 @@
 ========================================================
 
 Using a path patch to draw rectangles.
-The technique of using lots of Rectangle instances, or
-the faster method of using PolyCollections, were implemented before we
-had proper paths with moveto/lineto, closepoly etc in mpl.  Now that
-we have them, we can draw collections of regularly shaped objects with
-homogeneous properties more efficiently with a PathCollection. This
-example makes a histogram -- it's more work to set up the vertex arrays
-at the outset, but it should be much faster for large numbers of
-objects.
+
+The technique of using lots of `.Rectangle` instances, or the faster method of
+using `.PolyCollection`, were implemented before we had proper paths with
+moveto, lineto, closepoly, etc. in Matplotlib.  Now that we have them, we can
+draw collections of regularly shaped objects with homogeneous properties more
+efficiently with a PathCollection. This example makes a histogram -- it's more
+work to set up the vertex arrays at the outset, but it should be much faster
+for large numbers of objects.
 """
 
 import numpy as np
 import matplotlib.pyplot as plt
 import matplotlib.patches as patches
 import matplotlib.path as path
 
-fig, ax = plt.subplots()
-
-# Fixing random state for reproducibility
-np.random.seed(19680801)
+fig, axs = plt.subplots(2)
 
+np.random.seed(19680801)  # Fixing random state for reproducibility
 
 # histogram our data with numpy
-
 data = np.random.randn(1000)
 n, bins = np.histogram(data, 50)
 
@@ -36,28 +33,23 @@
 bottom = np.zeros(len(left))
 top = bottom + n
 
-
 # we need a (numrects x numsides x 2) numpy array for the path helper
 # function to build a compound path
 XY = np.array([[left, left, right, right], [bottom, top, top, bottom]]).T
 
 # get the Path object
 barpath = path.Path.make_compound_path_from_polys(XY)
 
-# make a patch out of it
+# make a patch out of it, don't add a margin at y=0
 patch = patches.PathPatch(barpath)
-ax.add_patch(patch)
-
-# update the view limits
-ax.set_xlim(left[0], right[-1])
-ax.set_ylim(bottom.min(), top.max())
-
-plt.show()
+patch.sticky_edges.y[:] = [0]
+axs[0].add_patch(patch)
+axs[0].autoscale_view()
 
 #############################################################################
-# It should be noted that instead of creating a three-dimensional array and
-# using `~.path.Path.make_compound_path_from_polys`, we could as well create
-# the compound path directly using vertices and codes as shown below
+# Instead of creating a three-dimensional array and using
+# `~.path.Path.make_compound_path_from_polys`, we could as well create the
+# compound path directly using vertices and codes as shown below
 
 nrects = len(left)
 nverts = nrects*(1+3+1)
@@ -76,6 +68,14 @@
 
 barpath = path.Path(verts, codes)
 
+# make a patch out of it, don't add a margin at y=0
+patch = patches.PathPatch(barpath)
+patch.sticky_edges.y[:] = [0]
+axs[1].add_patch(patch)
+axs[1].autoscale_view()
+
+plt.show()
+
 #############################################################################
 #
 # .. admonition:: References

lib/matplotlib/path.py

@@ -293,15 +293,15 @@ def __deepcopy__(self, memo=None):
     @classmethod
     def make_compound_path_from_polys(cls, XY):
         """
-        Make a compound path object to draw a number
-        of polygons with equal numbers of sides XY is a (numpolys x
-        numsides x 2) numpy array of vertices.  Return object is a
-        :class:`Path`.
+        Make a compound `Path` object to draw a number of polygons with equal
+        numbers of sides.
 
         .. plot:: gallery/misc/histogram_path.py
 
+        Parameters
+        ----------
+        XY : (numpolys, numsides, 2) array
         """
-
         # for each poly: 1 for the MOVETO, (numsides-1) for the LINETO, 1 for
         # the CLOSEPOLY; the vert for the closepoly is ignored but we still
         # need it to keep the codes aligned with the vertices
@@ -316,7 +316,6 @@ def make_compound_path_from_polys(cls, XY):
         codes[numsides::stride] = cls.CLOSEPOLY
         for i in range(numsides):
             verts[i::stride] = XY[:, i]
-
         return cls(verts, codes)
 
     @classmethod