Further work in polishing the documentation for the upcoming release.

WeatherGod · WeatherGod · commit 6c4e61d4633a · 2011-08-20T19:13:52.000-05:00
diff --git a/doc/mpl_toolkits/mplot3d/api.rst b/doc/mpl_toolkits/mplot3d/api.rst
@@ -19,6 +19,7 @@ mplot3d API
 
 .. automodule:: mpl_toolkits.mplot3d.axes3d
     :members:
+    :undoc-members:
     :show-inheritance:
 
 
@@ -38,6 +39,7 @@ mplot3d API
 
 .. automodule:: mpl_toolkits.mplot3d.axis3d
     :members:
+    :undoc-members:
     :show-inheritance:
 
 .. _toolkit_mplot3d-artapi:
@@ -47,6 +49,7 @@ mplot3d API
 
 .. automodule:: mpl_toolkits.mplot3d.art3d
     :members:
+    :undoc-members:
     :show-inheritance:
 
 .. _toolkit_mplot3d-projapi:
@@ -56,5 +59,6 @@ mplot3d API
 
 .. automodule:: mpl_toolkits.mplot3d.proj3d
     :members:
+    :undoc-members:
     :show-inheritance:
 
diff --git a/doc/users/legend_guide.rst b/doc/users/legend_guide.rst
@@ -4,8 +4,8 @@
 Legend guide
 ************
 
-Do not proceed unless you already have read :func:`~matplotlib.pyplot.legend` and
-:class:`matplotlib.legend.Legend`!
+Do not proceed unless you already have read :func:`~matplotlib.pyplot.legend`
+and :class:`matplotlib.legend.Legend`!
 
 
 What to be displayed
@@ -30,7 +30,7 @@ returns a tuple of two lists, i.e., list of artists and list of labels
 (python string).  However, it does not return all of its child
 artists. It returns artists that are currently supported by matplotlib.
 
-For matplotlib v1.0 and before, the supported artists are as follows.
+For matplotlib v1.0 and earlier, the supported artists are as follows.
 
    * :class:`~matplotlib.lines.Line2D`
    * :class:`~matplotlib.patches.Patch`
@@ -186,11 +186,12 @@ legend.
 .. plot:: users/plotting/examples/simple_legend02.py
    :include-source:
 
+.. _legend-complex-plots:
 
 Legend of Complex Plots
 =======================
 
-In matplotlib v1.1 (FIXME when released) and later, the legend is
+In matplotlib v1.1 and later, the legend is
 improved to support more plot commands and ease the customization.
 
 Artist Container
@@ -224,15 +225,15 @@ or ::
     legend([b1], ["Bar 1"])
 
 
-At this time of writing, however, "bar" and "errorbar" are only
+At this time of writing, however, only "bar", "errorbar", and "stem" are
 supported (hopefully the list will increase). Here is an example.
 
 .. plot:: mpl_examples/pylab_examples/legend_demo4.py
 
 Legend Handler
 --------------
 
-One of the change is that drawing of legend handles is delegated to
+One of the changes is that drawing of legend handles has been delegated to
 legend handlers. For example, :class:`~matplotlib.lines.Line2D`
 instances are handled by
 :class:`~matplotlib.legend_handler.HandlerLine2D`.  The mapping
@@ -247,8 +248,9 @@ Let's consider the following sample code, ::
 
 For each *p_i*, matplotlib
 
-  1. check if *p_i* itself is in the handler_map
-  2. if not, iterate over type(p_i).mro() until a matching key is found in the handler_map
+  1. check if *p_i* is in the handler_map
+  2. if not, iterate over type(p_i).mro() until a matching key is found
+     in the handler_map
 
 
 Unless specified, the defaul handler_map is used. Below is a partial
@@ -260,7 +262,7 @@ list of key-handler pairs included in the default handler map.
   * ...
 
 
-The legend command takes an optional argument of "handler_map". When
+The legend() command takes an optional argument of "handler_map". When
 provided, the default handler map will be updated (using dict.update
 method) with the provided one. ::
 
@@ -279,9 +281,9 @@ instances (p1 and p2). ::
 In the above example, only *p1* will be handled by *my_handler*, while
 others will be handled by default handlers.
 
-The curent default handler_map has handlers for errobar and bar
+The curent default handler_map has handlers for errorbar and bar
 plots. Also, it includes an entry for `tuple` which is mapped to
-`HandlerTuple`. It simply overplots all the handles for items in the
+`HandlerTuple`. It simply plots over all the handles for items in the
 given tuple. For example,
 
 
@@ -312,5 +314,5 @@ pixles, and *handlebox* is a OffsetBox instance. Within the call, you
 create relevant artists (using relevant properties from the *legend*
 and/or *orig_handle*) and add them into the handlebox. The artists
 needs to be scaled according to the fontsize (note that the size is in
-pixel, i.e., this is dpi-scaled value). See legend_handler.py for more
-details.
+pixel, i.e., this is dpi-scaled value). See :mod:`~matplotlib.legend_handler`
+for more details.
diff --git a/doc/users/whats_new.rst b/doc/users/whats_new.rst
@@ -19,24 +19,28 @@ Animation
 Ryan May invested significant effort to create a backend-independent
 framework for creating animated figures. The :mod:`~matplotlib.animation`
 module is intended to replace the difficult-to-understand,
-backend-specific examples that has existed in the examples listing.
+backend-specific examples that used to exist in the :ref:`examples-index`
+listings.
 
 This framework should be considered a beta feature for matplotlib, but
 we highly encourage users to try it out and provide feedback.
 
+Check out the :ref:`animation-examples-index` and try them out!
+
+
 Tight Layout
 ------------
 
 A frequent issue raised by users of matplotlib is the lack of a layout
-engine to nicely space out elements of the plots. While we still adhere
-to the philosphy of giving users complete control over the placement of
-plot elements, a :mod:`~matplotlib.tight_layout` module was created to
-address the most common layout issues.
+engine to nicely space out elements of the plots. While matplotlib still
+adheres to the philosphy of giving users complete control over the placement
+of plot elements, Jae-Joon Lee created the :mod:`~matplotlib.tight_layout`
+module to address the most common layout issues.
 
 :mod:`~matplotlib.tight_layout` will adjust the spacing between subplots
-so that the axis labels do not overlap with neighboring subplots.
-
-Need to acknowledge author
+so that the axis labels do not overlap with neighboring subplots. A
+:ref:`plotting-guide-tight-layout` has been created to show how to use
+this new tool.
 
 Full IPython 0.11 compatibility
 -------------------------------
@@ -49,11 +53,16 @@ is fully compatible with ipython.
 Legend
 ------
 
-Jae-Joon Lee has been working on revamping how plot legends are handled
+Jae-Joon Lee has also been working on revamping how plot legends are handled
 in matplotlib. This has resulted in some immediate enhancements. First,
-legends for :func:`~matplotlib.pyplot.stem` plots will now display
-correctly. Second, the 'best' placement of a legend has been improved
-in the presence of NaNs. 
+legends for complex plots such as :func:`~matplotlib.pyplot.stem` plots
+will now display correctly. Second, the 'best' placement of a legend has
+been improved in the presence of NANs.
+
+See :ref:`legend-complex-plots` for more detailed explanation and
+examples.
+
+.. plot:: mpl_examples/pylab_examples/legend_demo4.py
 
 mplot3d
 -------
@@ -66,14 +75,15 @@ as 2D plotting, Ben Root has made several improvements to the
   improved to bring the class towards feature-parity with regular
   Axes objects
 
-* Documentation for the mplot3d module was significantly expanded.
+* Documentation for :ref:`toolkit_mplot3d-index` was significantly expanded
 
 * Axis labels and orientation improved
 
 * Ticker offset display added
 
 * :func:`~mpl_toolkits.mplot3d.axes3d.Axes3D.contourf`
-  gains *zdir* and *offset* kwargs.
+  gains *zdir* and *offset* kwargs
+.. plot:: mpl_examples/mplot3d/contourf3d_demo2.py
 
 * Most 3D plotting functions now support empty inputs
 
diff --git a/lib/matplotlib/legend.py b/lib/matplotlib/legend.py
@@ -7,9 +7,9 @@
 plot elements in the axes or figures (e.g., lines, patches, etc.) are
 specified by the handler map, which defines the mapping between the
 plot elements and the legend handlers to be used (the default legend
-handlers are defined in the matplotlib.legend_handler module). Note
-that not all kinds of artist are supported by the legend yet (See LINK
-(FIXME) for details).
+handlers are defined in the :mod:`~matplotlib.legend_handler` module). Note
+that not all kinds of artist are supported by the legend yet (See
+:ref:`plotting-guide-legend` for more information).
 """
 from __future__ import division
 import warnings
