Rewrite of the entire legend documentation, including tidy ups of code

and style to all things "legend".

Author: pelson

doc/api/api_changes.rst

@@ -74,6 +74,16 @@ original location:
   thus `colorbar.ColorbarBase.outline` is now a
   `matplotlib.patches.Polygon` object.
 
+* The legend handler interface has changed from a callable, to any object
+  which implements the ``legend_artists`` method. See
+  :ref:`plotting-guide-legend` for further details. Further legend changes
+  include:
+
+   * :func:`matplotlib.axes.Axes._get_legend_handles` now returns a generator
+     of handles, rather than a list.
+
+   * The :func:`~matplotlib.pyplot.legend` function's "loc" positional
+     argument has been deprecated. Use the "loc" keyword instead.
 
 * The rcParams `savefig.transparent` has been added to control
   default transparency when saving figures.

doc/api/axes_api.rst

@@ -9,4 +9,3 @@ axes
 .. autoclass:: matplotlib.axes.Axes
    :members:
    :undoc-members:
- 

doc/api/legend_api.rst

@@ -1,5 +1,5 @@
 ******
-legend
+Legend
 ******
 
 
@@ -10,3 +10,9 @@ legend
    :members:
    :undoc-members:
    :show-inheritance:
+
+:mod:`matplotlib.legend_handler`
+================================
+.. automodule:: matplotlib.legend_handler
+      :members:
+      :undoc-members:

doc/api/matplotlib_configuration_api.rst

@@ -6,9 +6,9 @@ The top level :mod:`matplotlib` module
 
 .. autofunction:: use
 
-.. autofunction:: get_backend 
+.. autofunction:: get_backend
 
-.. py:data:: matplotlib.rcParams
+.. py:data:: rcParams
 
     An instance of :class:`RcParams` for handling default matplotlib values.
 

doc/api/offsetbox.rst

@@ -0,0 +1,12 @@
+*********
+offsetbox
+*********
+
+
+:mod:`matplotlib.offsetbox`
+===========================
+
+.. automodule:: matplotlib.offsetbox
+   :members:
+   :undoc-members:
+   :show-inheritance: