Tidied up some of the documentation.

doc/_templates/index.html

@@ -1,34 +1,8 @@
 {% extends "layout.html" %}
 {% set title = 'matplotlib: python plotting' %}
 
-
 {% block body %}
 
-  <h1>John Hunter (1968-2012)</h1>
-
-  <table bgcolor="#ddddff">
-    <tr>
-      <td>
-        <img src="_static/John-hunter-crop-2.jpg"/>
-        </td>
-      <td>
-  <p>
-  On August 28 2012, John D. Hunter, the creator of matplotlib, died
-  from complications arising from cancer treatment, after a brief but
-  intense battle with this terrible illness.  John is survived by his
-  wife Miriam, his three daughters Rahel, Ava and Clara, his sisters
-  Layne and Mary, and his mother Sarah.</p>
-
-  <p>
-  If you have benefited from John's many contributions, please say
-  thanks in the way that would matter most to him.  Please consider
-  making a donation to
-  the <a href="http://numfocus.org/johnhunter/">John Hunter Memorial
-  Fund</a>.</p>
-  </td>
-</tr>
-</table>
-
   <h1>Introduction</h1>
 
   <p>matplotlib is a python 2D plotting library which produces
@@ -66,6 +40,32 @@ <h1>Introduction</h1>
   properties, axes properties, etc, via an object oriented interface
   or via a set of functions familiar to MATLAB users.</p>
 
+<div style="float: right; min-width: 450px; width: 50%; padding-left: 5%;">
+  <h1>John Hunter (1968-2012)</h1>
+  <table bgcolor="#ddddff">
+   <tr>
+    <td>
+      <img src="_static/John-hunter-crop-2.jpg" align="left" />
+    </td>
+    <td>
+      <p>
+      On August 28 2012, John D. Hunter, the creator of matplotlib, died
+      from complications arising from cancer treatment, after a brief but
+      intense battle with this terrible illness.  John is survived by his
+      wife Miriam, his three daughters Rahel, Ava and Clara, his sisters
+      Layne and Mary, and his mother Sarah.</p>
+
+      <p>
+      If you have benefited from John's many contributions, please say
+      thanks in the way that would matter most to him.  Please consider
+      making a donation to
+      the <a href="http://numfocus.org/johnhunter/">John Hunter Memorial
+      Fund</a>.</p>
+    </td>
+   </tr>
+  </table>
+</div>
+
   <h1>Download</h1>
 
   Visit the
@@ -143,30 +143,31 @@ <h1>Toolkits</h1>
 <h1>Citing matplotlib</h1>
 
 <p>
-  matplotlib is the brainchild of John Hunter (1968-2012), who has put an
-  inordinate amount of effort into producing a piece of software utilized by
-  thousands of scientists worldwide.
+  matplotlib is the brainchild of John Hunter (1968-2012), who, along with its many
+  contributors, have put an immeasurable amount of time and effort into producing a
+  piece of software utilized by thousands of scientists worldwide.
 
   If matplotlib contributes to a project that leads to a scientific publication,
-  please acknowledge this fact by citing the project. You can use this
+  please acknowledge this work by citing the project. You can use this
   <a href="{{ pathto('citing') }}">ready-made citation entry</a>.
 </p>
 
   <h1>Open source</h1>
 
-<p>Please
-consider <a href="http://sourceforge.net/project/project_donations.php?group_id=80706">donating</a>
-to support matplotlib development or to
-the <a href="http://numfocus.org/johnhunter/">John Hunter Memorial
-Fund</a>.</p>
+<p>
+Please consider <a href="http://sourceforge.net/project/project_donations.php?group_id=80706">donating</a>
+to support matplotlib development or to the <a href="http://numfocus.org/johnhunter/">John Hunter Memorial Fund</a>.
+</p>
 
-<p>The matplotlib <a href="{{ pathto('users/license') }}">license</a>
-is based on the Python Software Foundation
-<a href="http://www.python.org/psf/license">(PSF)</a> license.</p>
+<p>
+The matplotlib <a href="{{ pathto('users/license') }}">license</a> is based on the Python Software Foundation
+<a href="http://www.python.org/psf/license">(PSF)</a> license.
+</p>
 
-<p>There is an active developer community and a long list of people
-who have made significant <a href="{{ pathto('users/credits')
-}}">contributions</a>.</p>
+<p>
+There is an active developer community and a long list of people
+who have made significant <a href="{{ pathto('users/credits') }}">contributions</a>.
+</p>
 
 
 <div class="footnote"><p>
@@ -178,6 +179,4 @@ <h1>Open source</h1>
 Mathematica is a registered trademark of Wolfram Research, Inc.
 </p>
 
-
-
 {% endblock %}

doc/_templates/layout.html

@@ -38,6 +38,7 @@
         <li><a href="{{ pathto('search') }}">search</a>|&nbsp;</li>
         <li><a href="{{ pathto('examples/index') }}">examples</a>|&nbsp;</li>
         <li><a href="{{ pathto('gallery') }}">gallery</a>|&nbsp;</li>
+        <li><a href="{{ pathto('api/pyplot_summary') }}">pyplot</a>|&nbsp;</li>
         <li><a href="{{ pathto('citing') }}">citation</a>|&nbsp;</li>
         <li><a href="{{ pathto('contents') }}">docs</a> &raquo;</li>
 {% endblock %}

doc/api/cm_api.rst

@@ -2,7 +2,6 @@
 cm (colormap)
 *************
 
-
 :mod:`matplotlib.cm`
 ====================
 

doc/api/colors_api.rst

@@ -2,6 +2,9 @@
 colors
 ******
 
+For a plot showing the available matplotlib colormaps see the
+:ref:`colormap <pylab_examples-show_colormaps>` example.
+
 
 :mod:`matplotlib.colors`
 ========================

doc/api/matplotlib_configuration_api.rst

@@ -1,13 +1,8 @@
-*************
-configuration
-*************
-
-
-:mod:`matplotlib`
-=================
+The top level :mod:`matplotlib` module
+======================================
 
 .. automodule:: matplotlib
    :members: rc, rcdefaults, use
+   :members:
    :undoc-members:
    :show-inheritance:
-

doc/mpl_toolkits/index.rst

@@ -22,13 +22,31 @@ Toolkits are collections of application-specific functions that extend matplotli
 
 .. _toolkit_basemap:
 
-Basemap
-=======
+Basemap (*Not distributed with matplotlib*)
+============================================
 
 Plots data on map projections, with continental and political
-boundaries, see `basemap <http://matplotlib.github.com/basemap>`_
+boundaries, see `basemap <http://matplotlib.org/basemap>`_
 docs.
 
+.. image:: http://matplotlib.org/basemap/_images/contour1.png
+    :height: 400px
+
+
+
+Cartopy  (*Not distributed with matplotlib*)
+============================================
+An alternative mapping library written for matplotlib ``v1.2`` and beyond.
+`Cartopy <http://scitools.org.uk/cartopy/docs/latest>`_ builds on top of
+matplotlib to provide object oriented map projection definitions and close
+integration with Shapely for powerful yet easy-to-use vector data processing
+tools. An example plot from the
+`Cartopy gallery <http://scitools.org.uk/cartopy/docs/latest/gallery.html>`_:
+
+.. image:: http://scitools.org.uk/cartopy/docs/latest/_images/hurricane_katrina_01_00.png
+    :height: 400px
+
+
 .. _toolkit_gtk:
 
 GTK Tools
@@ -38,6 +56,7 @@ mpl_toolkits.gtktools provides some utilities for working with GTK.
 This toolkit ships with matplotlib, but requires `pygtk
 <http://www.pygtk.org/>`_.
 
+
 .. _toolkit_excel:
 
 Excel Tools
@@ -47,38 +66,39 @@ mpl_toolkits.exceltools provides some utilities for working with
 Excel.  This toolkit ships with matplotlib, but requires
 `xlwt <http://pypi.python.org/pypi/xlwt>`_
 
+
 .. _toolkit_natgrid:
 
-Natgrid
-========
+Natgrid (*Not distributed with matplotlib*)
+===========================================
 
 mpl_toolkits.natgrid is an interface to natgrid C library for gridding
 irregularly spaced data.  This requires a separate installation of the
 natgrid toolkit from the sourceforge `download
 <http://sourceforge.net/project/showfiles.php?group_id=80706&package_id=142792>`_
 page.
 
+
 .. _toolkit_mplot3d:
 
 mplot3d
 ===========
 
-mpl_toolkits.mplot3d provides some basic 3D plotting (scatter, surf,
+:ref:`mpl_toolkits.mplot3d <toolkit_mplot3d-index>` provides some basic 3D plotting (scatter, surf,
 line, mesh) tools.  Not the fastest or feature complete 3D library out
 there, but ships with matplotlib and thus may be a lighter weight
 solution for some use cases.
 
-See :ref:`toolkit_mplot3d-index` for more documentation and examples.
+.. image:: /_images/contourf3d_demo21.png
+
 
 .. _toolkit_axes_grid:
 
 AxesGrid
 ========
 
-The matplotlib AxesGrid toolkit is a collection of helper classes to
+The matplotlib :ref:`AxesGrid <toolkit_axesgrid-index>` toolkit is a collection of helper classes to
 ease displaying multiple images in matplotlib. The AxesGrid toolkit is
 distributed with matplotlib source.
 
-.. image:: ../_static/demo_axes_grid.png
-
-See :ref:`toolkit_axesgrid-index` for documentations.
+.. image:: /_static/demo_axes_grid.png

examples/pylab_examples/marker_path.py

@@ -5,9 +5,9 @@
 
 star = mpath.Path.unit_regular_star(6)
 circle = mpath.Path.unit_circle()
-# concatenate the star with an internal cutout of the circle
-verts = np.concatenate([star.vertices, circle.vertices[::-1, ...]])
-codes = np.concatenate([star.codes, circle.codes])
+# concatenate the circle with an internal cutout of the star
+verts = np.concatenate([circle.vertices, star.vertices[::-1, ...]])
+codes = np.concatenate([circle.codes, star.codes])
 cut_star = mpath.Path(verts, codes)
 
 

examples/pylab_examples/pcolor_demo.py

@@ -1,28 +1,57 @@
-#!/usr/bin/env python
 """
-See pcolor_demo2 for an alternative way of generating pcolor plots
-using imshow that is likely faster for large grids
+Demonstrates similarities between pcolor, pcolormesh, imshow and pcolorfast
+for drawing quadrilateral grids.
+
 """
-from __future__ import division
-from matplotlib.patches import Patch
-from pylab import *
+import matplotlib.pyplot as plt
+import numpy as np
 
-def func3(x,y):
-    return (1- x/2 + x**5 + y**3)*exp(-x**2-y**2)
+# make these smaller to increase the resolution
+dx, dy = 0.15, 0.05
 
+# generate 2 2d grids for the x & y bounds
+y, x = np.mgrid[slice(-3, 3 + dy, dy),
+                slice(-3, 3 + dx, dx)]
+z = (1 - x / 2. + x ** 5 + y ** 3) * np.exp(-x ** 2 - y ** 2)
+# x and y are bounds, so z should be the value *inside* those bounds.
+# Therefore, remove the last value from the z array.
+z = z[:-1, :-1]
+z_min, z_max = -np.abs(z).max(), np.abs(z).max()
+
+
+
+plt.subplot(2, 2, 1)
+plt.pcolor(x, y, z, cmap='RdBu', vmin=z_min, vmax=z_max)
+plt.title('pcolor')
+# set the limits of the plot to the limits of the data
+plt.axis([x.min(), x.max(), y.min(), y.max()])
+plt.colorbar()
+
+
+
+plt.subplot(2, 2, 2)
+plt.pcolormesh(x, y, z, cmap='RdBu', vmin=z_min, vmax=z_max)
+plt.title('pcolormesh')
+# set the limits of the plot to the limits of the data
+plt.axis([x.min(), x.max(), y.min(), y.max()])
+plt.colorbar()
+
+
+
+plt.subplot(2, 2, 3)
+plt.imshow(z, cmap='RdBu', vmin=z_min, vmax=z_max,
+           extent=[x.min(), x.max(), y.min(), y.max()],
+           interpolation='nearest', origin='lower')
+plt.title('image (interp. nearest)')
+plt.colorbar()
 
-# make these smaller to increase the resolution
-dx, dy = 0.05, 0.05
 
-x = arange(-3.0, 3.0001, dx)
-y = arange(-3.0, 3.0001, dy)
-X,Y = meshgrid(x, y)
 
-Z = func3(X, Y)
-pcolor(X, Y, Z, cmap=cm.RdBu, vmax=abs(Z).max(), vmin=-abs(Z).max())
-colorbar()
-axis([-3,3,-3,3])
+ax = plt.subplot(2, 2, 4)
+ax.pcolorfast(x, y, z, cmap='RdBu', vmin=z_min, vmax=z_max)
+plt.title('pcolorfast')
+plt.colorbar()
 
-show()
 
 
+plt.show()