Merged from main/master

Author: mdboom

CHANGELOG

@@ -1,8 +1,46 @@
+2011-08-18 Change api of Axes.get_tightbbox and add an optional
+           keyword parameter *call_axes_locator*. - JJL
+
+2011-07-29 A new rcParam "axes.formatter.use_locale" was added, that,
+           when True, will use the current locale to format tick
+           labels.  This means that, for example, in the fr_FR locale,
+           ',' will be used as a decimal separator.  - MGD
+
+2011-07-15 The set of markers available in the plot() and scatter()
+           commands has been unified.  In general, this gives more
+           options to both than were previously available, however,
+           there is one backward-incompatible change to the markers in
+           scatter:
+
+              "d" used to mean "diamond", it now means "narrow
+              diamond".  "D" can be used for a "diamond".
+
+           -MGD
+
+2011-07-13 Fix numerical problems in symlog scale, particularly when
+           linthresh <= 1.0.  Symlog plots may look different if one
+           was depending on the old broken behavior - MGD
+
+2011-07-10 Fixed argument handling error in tripcolor/triplot/tricontour,
+           issue #203. - IMT
+
+2011-07-08 Many functions added to mplot3d.axes3d to bring Axes3D
+           objects more feature-parity with regular Axes objects.
+           Significant revisions to the documentation as well.
+           - BVR
+
 2011-06-28 3D versions of scatter, plot, plot_wireframe, plot_surface,
            bar3d, and some other functions now support empty inputs. - BVR
 
-2011-06-16 Added *bottom* keyword parameter for the stem command. 
-           Also, implemented a legend handler for the stem plot. 
+2011-06-22 Add set_theta_offset, set_theta_direction and
+           set_theta_zero_location to polar axes to control the
+           location of 0 and directionality of theta. - MGD
+
+2011-06-22 Add axes.labelweight parameter to set font weight to axis
+           labels - MGD.
+
+2011-06-16 Added *bottom* keyword parameter for the stem command.
+           Also, implemented a legend handler for the stem plot.
            - JJL
 
 2011-04-17 Disable keyboard auto-repeat in qt4 backend by ignoring

doc/_static/demo_mplot3d.png

@@ -5,8 +5,10 @@ <h3>News</h3>
 to support matplotlib development.</p>
 
 
-<p>matplotlib 1.0.1 is available for <a href="https://sourceforge.net/projects/matplotlib/files/matplotlib/matplotlib-1.0.1/">download</a>.  See <a href="{{ pathto('users/whats_new') }}">what's new</a> and tips on <a href="{{
-pathto('users/installing') }}">installing</a>
+<p>Matplotlib 1.1.0 is available for
+<a href="https://sourceforge.net/projects/matplotlib/files/matplotlib/matplotlib-1.1.0/">download</a>.
+See <a href="{{ pathto('users/whats_new') }}">what's new</a>
+and tips on <a href="{{ pathto('users/installing') }}">installing</a>.
 </p>
 
 <p>Sandro Tosi has a new book
@@ -16,7 +18,7 @@ <h3>News</h3>
   at <a href="http://www.amazon.com/Matplotlib-Python-Developers-Sandro-Tosi/dp/1847197906">amazon</a>.</p>
 
 <p>Build websites like matplotlib's,
-with <a href="http://sphinx.pocoo.org/">sphinx</a> and extensions for
+with <a href="http://sphinx.pocoo.org/">Sphinx</a> and extensions for
 mpl plots, math, inheritance diagrams -- try
 the <a href="http://matplotlib.sf.net/sampledoc">sampledoc</a>
 tutorial.
@@ -38,7 +40,7 @@ <h3>Videos</h3>
 
 <h3>Toolkits</h3>
 
-<p>There are several matplotlib addon <a href="{{
+<p>There are several matplotlib add-on <a href="{{
 pathto('users/toolkits') }}">toolkits</a>, including the projection
 and mapping toolkit
 <a href="http://matplotlib.sf.net/basemap/doc/html">basemap</a>, 3d plotting with <a href="{{
@@ -59,8 +61,8 @@ <h3>Need help?</h3>
 examples which exercise almost every corner of matplotlib.</p>
 
 <p>You can file bugs, patches and feature requests on the
-sourceforge
-<a href="http://sourceforge.net/tracker2/?group_id=80706">tracker</a>,
+github
+<a href="https://github.com/matplotlib/matplotlib/issues?sort=created&direction=desc&state=open">tracker</a>,
 but it is a good idea to ping us on the mailing list too.</p>
 
 <p>For details on what's new, see the detailed <a href="{{

doc/_templates/indexsidebar.html

@@ -23,7 +23,7 @@ in mind.
 * Can you pass :file:`examples/tests/backend_driver.py`?  This is our
   poor man's unit test.
 
-* Can you add a test to :file:`unit/nose_tests.py` to test your changes?
+* Can you add a test to :file:`lib/matplotlib/tests` to test your changes?
 
 * If you have altered extension code, do you pass
   :file:`unit/memleak_hawaii3.py`?
@@ -33,7 +33,7 @@ in mind.
   :file:`MANIFEST.in`.  This file determines what goes into the source
   distribution of the mpl build.
 
-* Keep the maintenance branches and trunk in sync where it makes sense.
+* Keep the maintenance branches and master in sync where it makes sense.
 
 Style guide
 ===========
@@ -101,8 +101,8 @@ To detect and fix these and other whitespace errors (see below),
 use `reindent.py
 <http://svn.python.org/projects/doctools/trunk/utils/reindent.py>`_ as
 a command-line script.  Unless you are sure your editor always
-does the right thing, please use reindent.py before checking changes into
-svn.
+does the right thing, please use reindent.py before committing your
+changes in git.
 
 Keep docstrings_ uniformly indented as in the example below, with
 nothing to the left of the triple quotes.  The
@@ -116,7 +116,7 @@ It may be preferable to use a temporary variable to replace a single
 long line with two shorter and more readable lines.
 
 Please do not commit lines with trailing white space, as it causes
-noise in svn diffs.  Tell your editor to strip whitespace from line
+noise in git diffs.  Tell your editor to strip whitespace from line
 ends when saving a file.  If you are an emacs user, the following in
 your ``.emacs`` will cause emacs to strip trailing white space upon
 saving for python, C and C++:
@@ -324,43 +324,32 @@ Writing examples
 ================
 
 We have hundreds of examples in subdirectories of
-file:`matplotlib/examples` in the trunk, and these are automatically
-generated when the website it built to show up both in the `examples
+file:`matplotlib/examples`, and these are automatically
+generated when the website is built to show up both in the `examples
 <http://matplotlib.sourceforge.net/examples/index.html>`_ and `gallery
 <http://matplotlib.sourceforge.net/gallery.html>`_ sections of the
 website.  Many people find these examples from the website, and do not
 have ready access to the file:`examples` directory in which they
 reside.  Thus any example data that is required for the example should
-be provided through the sample_data svn directory, which can then be
-accessed using :func:`matplotlib.cbook.get_sample_data`.  First get a
-copy of the repository and svn add your data::
-
-    svn co https://matplotlib.svn.sourceforge.net/svnroot/matplotlib/trunk/sample_data
-    cp ~/path/to/mydata.dat sample_data/
-    cd sample_data
-    svn add mydata.dat
-    svn commit -m 'added my data'
-
-and then in your example code you can load it into a file handle with::
+be added to the `sample_data
+<https://github.com/matplotlib/sample_data>`_ git repository.
+Then in your example code you can load it into a file handle with::
 
     import matplotlib.cbook as cbook
     fh = cbook.get_sample_data('mydata.dat')
 
-The file will be fetched from the svn repo using urllib and updated
+The file will be fetched from the git repo using urllib and updated
 when the revision number changes.
 
 
-If you prefer just to get the full path to the file instead of an file
+If you prefer just to get the full path to the file instead of a file
 object::
 
     import matplotlib.cbook as cbook
     datafile = cbook.get_sample_data('mydata.dat', asfileobj=False)
     print 'datafile', datafile
 
 
-
-
-
 Testing
 =======
 

doc/devel/coding_guide.rst

@@ -1,24 +1,60 @@
+.. _toolkit_mplot3d-api:
+
 ***********
 mplot3d API
 ***********
+.. contents::
+      :backlinks: none
 
-:mod:`mpl_toolkits.mplot3d.axes3d`
-==================================
+.. _toolkit_mplot3d-axesapi:
+
+:mod:`~mpl_toolkits.mplot3d.axes3d`
+===================================
+
+.. note::
+   Significant effort went into bringing axes3d to feature-parity with
+   regular axes objects for version 1.1.0. However, more work remains.
+   Please report any functions that do not behave as expected as a bug.
+   In addition, help and patches would be greatly appreciated!
 
 .. automodule:: mpl_toolkits.mplot3d.axes3d
     :members:
     :show-inheritance:
 
-:mod:`mpl_toolkits.mplot3d.art3d`
-=================================
 
-.. automodule:: mpl_toolkits.mplot3d.art3d
+.. _toolkit_mplot3d-axisapi:
+
+:mod:`~mpl_toolkits.mplot3d.axis3d`
+===================================
+
+.. note::
+   Historically, axis3d has suffered from having hard-coded constants
+   controlling the look and feel of the 3D plot. This precluded user
+   level adjustments such as label spacing, font colors and panel colors.
+   For version 1.1.0, these constants have been consolidated into a single
+   private member dictionary, `self._axinfo`, for the axis object. This is
+   intended only as a stop-gap measure to allow user-level customization,
+   but it is not intended to be permanent.
+
+.. automodule:: mpl_toolkits.mplot3d.axis3d
     :members:
     :show-inheritance:
 
-:mod:`mpl_toolkits.mplot3d.proj3d`
+.. _toolkit_mplot3d-artapi:
+
+:mod:`~mpl_toolkits.mplot3d.art3d`
 ==================================
 
+.. automodule:: mpl_toolkits.mplot3d.art3d
+    :members:
+    :show-inheritance:
+
+.. _toolkit_mplot3d-projapi:
+
+:mod:`~mpl_toolkits.mplot3d.proj3d`
+===================================
+
 .. automodule:: mpl_toolkits.mplot3d.proj3d
     :members:
     :show-inheritance:
+

doc/mpl_toolkits/mplot3d/api.rst

@@ -0,0 +1,52 @@
+.. _toolkit_mplot3d-faq:
+
+***********
+mplot3d FAQ
+***********
+
+How is mplot3d different from MayaVi?
+=====================================
+`MayaVi2 <http://code.enthought.com/projects/mayavi/documentation.php>`_
+is a very powerful and featureful 3D graphing library. For advanced
+3D scenes and excellent rendering capabilities, it is highly recomended to
+use MayaVi2.
+
+mplot3d was intended to allow users to create simple 3D graphs with the same
+"look-and-feel" as matplotlib's 2D plots. Furthermore, users can use the same
+toolkit that they are already familiar with to generate both their 2D and 3D
+plots.
+
+
+My 3D plot doesn't look right at certain viewing angles
+=======================================================
+This is probably the most commonly reported issue with mplot3d. The problem
+is that -- from some viewing angles -- a 3D object would appear in front
+of another object, even though it is physically behind it. This can result in
+plots that do not look "physically correct."
+
+Unfortunately, while some work is being done to reduce the occurance of this
+artifact, it is currently an intractable problem, and can not be fully solved
+until matplotlib supports 3D graphics rendering at its core.
+
+The problem occurs due to the reduction of 3D data down to 2D + z-order
+scalar. A single value represents the 3rd dimension for all parts of 3D
+objects in a collection. Therefore, when the bounding boxes of two collections
+intersect, it becomes possible for this artifact to occur. Furthermore, the
+intersection of two 3D objects (such as polygons or patches) can not be
+rendered properly in matplotlib's 2D rendering engine.
+
+This problem will likely not be solved until OpenGL support is added to all of
+the backends (patches are greatly welcomed). Until then, if you need complex
+3D scenes, we recommend using
+`MayaVi <http://code.enthought.com/projects/mayavi/documentation.php>`_.
+
+
+I don't like how the 3D plot is laid out, how do I change that?
+===============================================================
+Historically, mplot3d has suffered from a hard-coding of parameters used
+to control visuals such as label spacing, tick length, and grid line width.
+Work is being done to eliminate this issue. For matplotlib v1.1.0, there is
+a semi-official manner to modify these parameters. See the note in the
+:ref:`toolkit_mplot3d-axisapi` section of the mplot3d API documentation for
+more information.
+

doc/mpl_toolkits/mplot3d/faq.rst

@@ -7,16 +7,21 @@ mplot3d
 
 Matplotlib mplot3d toolkit
 ==========================
-The mplot3d toolkit adds simple 3d plotting capabilities to matplotlib by
-supplying an axis object that can create a 2d projection of a 3d scene.
-The resulting graph will have the same look and feel as regular 2d plots.
+The mplot3d toolkit adds simple 3D plotting capabilities to matplotlib by
+supplying an axes object that can create a 2D projection of a 3D scene.
+The resulting graph will have the same look and feel as regular 2D plots.
+
+.. image:: ../../_static/demo_mplot3d.png
 
 The interactive backends also provide the ability to rotate and zoom
-the 3d scene.
+the 3D scene. One can rotate the 3D scene by simply clicking-and-dragging
+the scene. Zooming is done by right-clicking the scene and dragging the
+mouse up and down. Note that one does not use the zoom button like one
+would use for regular 2D plots.
 
 .. toctree::
     :maxdepth: 2
 
     tutorial.rst
     api.rst
-
+    faq.rst

doc/mpl_toolkits/mplot3d/index.rst

@@ -22,10 +22,10 @@ add a new axes to it of type :class:`~mpl_toolkits.mplot3d.Axes3D`::
   ax = fig.add_subplot(111, projection='3d')
 
 .. versionadded:: 1.0.0
-   This approach is the preferred method of creating a 3d axes.
+   This approach is the preferred method of creating a 3D axes.
 
 .. note::
-   Prior to version 1.0.0, the method of creating a 3d axes was
+   Prior to version 1.0.0, the method of creating a 3D axes was
    different. For those using older versions of matplotlib, change
    ``ax = fig.add_subplot(111, projection='3d')``
    to ``ax = Axes3D(fig)``.
@@ -121,12 +121,12 @@ Text
 
 Subplotting
 ====================
-Having multiple 3d plots in a single figure is the same
-as it is for 2d plots. Also, you can have both 2d and 3d plots
+Having multiple 3D plots in a single figure is the same
+as it is for 2D plots. Also, you can have both 2D and 3D plots
 in the same figure.
 
 .. versionadded:: 1.0.0
-   Subplotting 3d plots was added in v1.0.0.  Earlier version can not
+   Subplotting 3D plots was added in v1.0.0.  Earlier version can not
    do this.
 
 .. plot:: mpl_examples/mplot3d/subplot3d_demo.py

doc/mpl_toolkits/mplot3d/tutorial.rst

@@ -1,8 +1,14 @@
+import matplotlib.pyplot as plt
+import numpy as np
+
 try:
     from mpl_toolkits.basemap import Basemap
-    import matplotlib.pyplot as plt
-    import numpy as np
+    have_basemap = True
+except ImportError:
+    have_basemap = False
+
 
+def plotmap():
     # create figure
     fig = plt.figure(figsize=(8,8))
     # set up orthographic map projection with
@@ -40,6 +46,16 @@
     # draw blue marble image in background.
     # (downsample the image by 50% for speed)
     map.bluemarble(scale=0.5)
-    plt.show()
-except ImportError:
-    pass
+
+def plotempty():
+    # create figure
+    fig = plt.figure(figsize=(8,8))
+    fig.text(0.5, 0.5, "Sorry, could not import Basemap",
+                                horizontalalignment='center')
+
+if have_basemap:
+    plotmap()
+else:
+    plotempty()
+plt.show()
+