Merge pull request #6557 from jenshnielsen/2xmaster

Merge 2.x to master

INSTALL

@@ -1,6 +1,7 @@
 .. The source of this document is INSTALL. During the doc build process,
 .. this file is copied over to doc/users/installing.rst.
 .. Therefore, you must edit INSTALL, *not* doc/users/installing.rst!
+.. _pip: https://pypi.python.org/pypi/pip/
 
 **********
 Installing
@@ -21,14 +22,12 @@ Most platforms : scientific Python distributions
 The first option is to use one of the pre-packaged python
 distributions that already provide matplotlib built-in.  The
 Continuum.io Python distribution (`Anaconda
-<https://store.continuum.io/cshop/anaconda/>`_ or `miniconda
+<https://www.continuum.io/downloads/>`_ or `miniconda
 <http://conda.pydata.org/miniconda.html>`_) and the Enthought
 distribution `(Canopy) <https://www.enthought.com/products/canopy/>`_
 are both excellent choices that "just work" out of the box for
 Windows, OSX and common Linux platforms.  Both of these distributions
-include matplotlib and *lots* of other useful tools.  Another
-excellent alternative for Windows users is `Python (x, y)
-<https://code.google.com/p/pythonxy>`_ .
+include matplotlib and *lots* of other useful tools.
 
 
 Linux : using your package manager
@@ -44,43 +43,36 @@ Mac OSX : using pip
 -------------------
 
 If you are on Mac OSX you can probably install matplotlib binaries using the
-standard Python installation program `pip <https://pypi.python.org/pypi/pip>`_.
+standard Python installation program pip_.
 See :ref:`install_osx_binaries`.
 
+.. _installing_windows:
 
 Windows
 -------
 
 If you don't already have Python installed, we recommend using
 one of the `scipy-stack compatible Python distributions
 <http://www.scipy.org/install.html>`_ such as WinPython, Python(x,y),
-Enthought Canopy, or Continuum Anaconda, which have matplotlib and
-many of its dependencies, plus other useful packages, preinstalled.
-
-For `standard Python <http://www.python.org/download/>`_ installations
-you will also need to install compatible versions of
-`setuptools <https://pypi.python.org/pypi/setuptools/>`_,
-`numpy <https://pypi.python.org/pypi/numpy/>`_,
-`python-dateutil <https://pypi.python.org/pypi/python-dateutil/>`_,
-`pytz <https://pypi.python.org/pypi/pytz>`_,
-`pyparsing <https://pypi.python.org/pypi/pyparsing/>`_, and
-`cycler <https://pypi.python.org/pypi/Cycler>`_
-in addition to
-`matplotlib <http://pypi.python.org/pypi/matplotlib/>`_.
-
-For Python 3.5 the `Visual C++ Redistributable for Visual Studio 2015
-<http://www.microsoft.com/en-us/download/details.aspx?id=48145>`_
-needs to be installed.
-In case Python 2.7 to 3.4 are not installed for all users (not the default),
+Enthought Canopy, or Continuum Anaconda, which have matplotlib and many
+of its dependencies, plus other useful packages, preinstalled.
+
+For `standard Python <https://www.python.org/download/>`_ installations,
+install matplotlib using pip_::
+
+    python -m pip install -U pip setuptools
+    python -m pip install matplotlib
+
+In case Python 2.7 or 3.4 are not installed for all users,
 the Microsoft Visual C++ 2008 (
 `64 bit <http://www.microsoft.com/download/en/details.aspx?id=15336>`__
 or
 `32 bit <http://www.microsoft.com/download/en/details.aspx?id=29>`__
-for Python 2.7 to 3.2) or Microsoft Visual C++ 2010 (
+for Python 2.7) or Microsoft Visual C++ 2010 (
 `64 bit <http://www.microsoft.com/en-us/download/details.aspx?id=14632>`__
 or
 `32 bit <http://www.microsoft.com/en-us/download/details.aspx?id=5555>`__
-for Python 3.3 and 3.4) redistributable packages need to be installed.
+for Python 3.4) redistributable packages need to be installed.
 
 Matplotlib depends on `Pillow <https://pypi.python.org/pypi/Pillow>`_
 for reading and saving JPEG, BMP, and TIFF image files.
@@ -105,22 +97,23 @@ For other backends you may need to install
 or GhostScript.
 
 TkAgg is probably the best backend for interactive use from the
-standard Python shell or IPython. It is enabled as the default backend
+standard Python shell or IPython.  It is enabled as the default backend
 for the official binaries.  GTK3 is not supported on Windows.
 
-The Windows installers (:file:`*.exe`) and wheels (:file:`*.whl`) on
-the `PyPI download page <http://pypi.python.org/pypi/matplotlib/>`_ do
-not contain test data or example code.  If you want to try the many
-demos that come in the matplotlib source distribution, download the
-:file:`*.tar.gz` file and look in the :file:`examples` subdirectory.
-To run the test suite, copy the :file:`lib\matplotlib\tests` and
-:file:`lib\mpl_toolkits\tests` directories from the source
-distribution to :file:`sys.prefix\Lib\site-packages\matplotlib` and
-:file:`sys.prefix\Lib\site-packages\mpl_toolkits` respectively, and
+The Windows wheels (:file:`*.whl`) on the `PyPI download page
+<https://pypi.python.org/pypi/matplotlib/>`_ do not contain test data
+or example code.
+If you want to try the many demos that come in the matplotlib source
+distribution, download the :file:`*.tar.gz` file and look in the
+:file:`examples` subdirectory.
+To run the test suite, copy the :file:`lib\\matplotlib\\tests` and
+:file:`lib\\mpl_toolkits\\tests` directories from the source
+distribution to :file:`sys.prefix\\Lib\\site-packages\\matplotlib` and
+:file:`sys.prefix\\Lib\\site-packages\\mpl_toolkits` respectively, and
 install `nose <https://pypi.python.org/pypi/nose>`_, `mock
 <https://pypi.python.org/pypi/mock>`_, Pillow, MiKTeX, GhostScript,
 ffmpeg, avconv, mencoder, ImageMagick, and `Inkscape
-<http://inkscape.org/>`_.
+<https://inkscape.org/>`_.
 
 
 
@@ -327,17 +320,14 @@ git repository and follow the instruction in :file:`README.osx`.
 
 .. _build_windows:
 
-
 Building on Windows
 -------------------
 
 The Python shipped from http://www.python.org is compiled with Visual Studio
-2008 for versions before 3.3 and Visual Studio 2010 for 3.3 and later.  Python
-extensions are recommended to be compiled with the same compiler.  The .NET
-Framework 4.0 is required for MSBuild (you'll likely have the requisite
-Framework with Visual Studio).  In addition to Visual Studio `CMake
-<http://www.cmake.org>`_ is required for building libpng.
-
-Since there is no canonical Windows package manager the build methods for
-freetype, zlib, libpng, tcl, & tk source code are documented as a build script
+2008 for versions before 3.3, Visual Studio 2010 for 3.3 and 3.4, and
+Visual Studio 2015 for 3.5.  Python extensions are recommended to be compiled
+with the same compiler.
+
+Since there is no canonical Windows package manager, the methods for building
+freetype, zlib, and libpng from source code are documented as a build script
 at `matplotlib-winbuild <https://github.com/jbmohler/matplotlib-winbuild>`_.

doc/_templates/index.html

@@ -65,7 +65,7 @@ <h1>Introduction</h1>
   You can generate plots, histograms, power spectra, bar charts,
   errorcharts, scatterplots, etc, with just a few lines of code.
   For a sampling, see the <a href="{{ pathto('users/screenshots') }}">screenshots</a>, <a href="{{ pathto('gallery') }}">thumbnail</a> gallery,  and
-    <a href="examples/index.html">examples</a> directory</p>
+    <a href="{{ pathto('examples/index') }}">examples</a> directory</p>
 
 <p>For simple plotting the <tt>pyplot</tt> interface provides a
   MATLAB-like interface, particularly when combined
@@ -102,9 +102,7 @@ <h1>John Hunter (1968-2012)</h1>
 
   <h1>Installation</h1>
 
-  Visit the
-  <a href="http://matplotlib.org/users/installing.html">matplotlib
-  installation instructions.</a>.
+  Visit the <a href="{{ pathto('users/installing') }}">matplotlib installation instructions</a>.
 
   <h1>Documentation</h1>
 
@@ -116,8 +114,8 @@ <h1>Documentation</h1>
   </script>
 
   <p>Trying to learn how to do a particular kind of plot?  Check out
-  the <a href="gallery.html">gallery</a>, <a href="examples/index.html">examples</a>,
-  or the <a href="api/pyplot_summary.html">list of plotting
+  the <a href="{{ pathto('gallery') }}">gallery</a>, <a href="{{ pathto('examples/index') }}">examples</a>,
+  or the <a href="{{ pathto('api/pyplot_summary') }}">list of plotting
   commands</a>.</p>
 
   <h4>Other learning resources</h4>

doc/_templates/layout.html

@@ -168,8 +168,11 @@ <h3>{{ _('Navigation') }}</h3>
 </map>
 
 <div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px">
-<a href="{{ pathto('index') }}"><img src="{{
-pathto("_static/logo2.svg", 1) }}" width="540px" border="0" alt="matplotlib"/></a>
+{%- if builder in ('htmlhelp', 'devhelp', 'latex') %}
+<a href="{{ pathto('index') }}"><img src="{{pathto("_static/logo2.png", 1) }}" width="540px" border="0" alt="matplotlib"/></a>
+{%- else %}
+<a href="{{ pathto('index') }}"><img src="{{pathto("_static/logo2.svg", 1) }}" width="540px" border="0" alt="matplotlib"/></a>
+{%- endif %}
 </div>
 
 {% endblock %}

doc/faq/installing_faq.rst

@@ -52,31 +52,6 @@ matplotlib was originally installed on your system. Follow the steps
 below that goes with your original installation method to cleanly
 remove matplotlib from your system.
 
-Easy Install
-------------
-
-1. Delete the caches from your :ref:`.matplotlib configuration directory
-   <locating-matplotlib-config-dir>`.
-
-2. Run::
-
-     easy_install -m matplotlib
-
-
-3. Delete any .egg files or directories from your :ref:`installation
-   directory <locating-matplotlib-install>`.
-
-
-
-Windows installer
------------------
-
-1. Delete the caches from your :ref:`.matplotlib configuration directory
-   <locating-matplotlib-config-dir>`.
-
-2. Use :menuselection:`Start --> Control Panel` to start the :program:`Add and
-   Remove Software` utility.
-
 Source install
 --------------
 
@@ -374,24 +349,4 @@ know: see :ref:`reporting-problems`.
 Windows Notes
 =============
 
-We recommend you use one of the excellent python collections which include
-Python itself and a wide range of libraries including matplotlib:
-
-- Anaconda_ from `Continuum Analytics`_
-- Canopy_ from Enthought_
-- `Python (x, y) <https://code.google.com/p/pythonxy>`_
-
-Python (X, Y) is Windows-only, whereas Anaconda and Canopy are cross-platform.
-
-.. _windows-installers:
-
-Standalone binary installers for Windows
-----------------------------------------
-
-If you have already installed Python and numpy, you can use one of the
-matplotlib binary installers for windows -- you can get these from the
-`the PyPI matplotlib page <http://pypi.python.org/pypi/matplotlib>`_
-site.  Choose the files with an ``.exe`` extension that match your
-version of Python (e.g., ``py2.7`` if you installed Python 2.7).  If
-you haven't already installed Python, you can get the official version
-from the `Python web site <http://python.org/download/>`_.
+See :ref:`installing_windows`.

examples/color/named_colors.py

@@ -27,7 +27,7 @@
 ncols = 4
 nrows = int(np.ceil(1. * n / ncols))
 
-fig, ax = plt.subplots()
+fig, ax = plt.subplots(figsize=(8, 5))
 
 X, Y = fig.get_dpi() * fig.get_size_inches()
 
@@ -49,10 +49,6 @@
             horizontalalignment='left',
             verticalalignment='center')
 
-    # Add extra black line a little bit thicker to make
-    # clear colors more visible.
-    ax.hlines(
-        y, xi_line, xf_line, color='black', linewidth=(h * 0.7))
     ax.hlines(
         y + h * 0.1, xi_line, xf_line, color=colors[name], linewidth=(h * 0.6))
 

examples/pylab_examples/csd_demo.py

@@ -4,8 +4,10 @@
 import numpy as np
 import matplotlib.pyplot as plt
 
+
+fig, (ax1, ax2) = plt.subplots(2, 1)
 # make a little extra space between the subplots
-plt.subplots_adjust(wspace=0.5)
+fig.subplots_adjust(hspace=0.5)
 
 dt = 0.01
 t = np.arange(0, 30, dt)
@@ -20,14 +22,12 @@
 s1 = 0.01*np.sin(2*np.pi*10*t) + cnse1
 s2 = 0.01*np.sin(2*np.pi*10*t) + cnse2
 
-plt.subplot(211)
-plt.plot(t, s1, t, s2)
-plt.xlim(0, 5)
-plt.xlabel('time')
-plt.ylabel('s1 and s2')
-plt.grid(True)
+ax1.plot(t, s1, t, s2)
+ax1.set_xlim(0, 5)
+ax1.set_xlabel('time')
+ax1.set_ylabel('s1 and s2')
+ax1.grid(True)
 
-plt.subplot(212)
-cxy, f = plt.csd(s1, s2, 256, 1./dt)
-plt.ylabel('CSD (db)')
+cxy, f = ax2.csd(s1, s2, 256, 1./dt)
+ax2.set_ylabel('CSD (db)')
 plt.show()

examples/showcase/bachelors_degrees_by_gender.py

@@ -27,10 +27,12 @@
 ax.get_xaxis().tick_bottom()
 ax.get_yaxis().tick_left()
 
+fig.subplots_adjust(left=.06, right=.75, bottom=.02, top=.94)
 # Limit the range of the plot to only where the data is.
 # Avoid unnecessary whitespace.
-plt.xlim(1968.5, 2011.1)
-plt.ylim(-0.25, 90)
+ax.set_xlim(1968.5, 2011.1)
+ax.set_ylim(-0.25, 90)
+ax.get_xaxis().get_major_formatter().set_useOffset(False)
 
 # Make sure your axis ticks are large enough to be easily read.
 # You don't want your viewers squinting to read your plot.
@@ -91,10 +93,10 @@
 
 # Note that if the title is descriptive enough, it is unnecessary to include
 # axis labels; they are self-evident, in this plot's case.
-plt.title('Percentage of Bachelor\'s degrees conferred to women in '
-          'the U.S.A. by major (1970-2011)\n', fontsize=18, ha='center')
+fig.suptitle('Percentage of Bachelor\'s degrees conferred to women in '
+             'the U.S.A. by major (1970-2011)\n', fontsize=18, ha='center')
 
 # Finally, save the figure as a PNG.
 # You can also save it as a PDF, JPEG, etc.
 # Just change the file extension in this call.
-plt.savefig('percent-bachelors-degrees-women-usa.png', bbox_inches='tight')
+# plt.savefig('percent-bachelors-degrees-women-usa.png', bbox_inches='tight')

lib/matplotlib/axes/_axes.py

@@ -635,63 +635,13 @@ def text(self, x, y, s, fontdict=None,
 
     @docstring.dedent_interpd
     def annotate(self, *args, **kwargs):
-        """
-        Create an annotation: a piece of text referring to a data
-        point.
-
-        Parameters
-        ----------
-        s : string
-            label
-
-        xy : (x, y)
-            position of element to annotate. See *xycoords* to control what
-            coordinate system this value is interpretated in.
-
-        xytext : (x, y) , optional, default: None
-            position of the label `s`. See *textcoords* to control what
-            coordinate system this value is interpreted in.
-
-        xycoords : string, optional, default: "data"
-            string that indicates what type of coordinates `xy` is. Examples:
-            "figure points", "figure pixels", "figure fraction", "axes
-            points", .... See `matplotlib.text.Annotation` for more details.
-
-        textcoords : string, optional, default: None
-            string that indicates what type of coordinates `text` is. Examples:
-            "figure points", "figure pixels", "figure fraction", "axes
-            points", .... See `matplotlib.text.Annotation` for more details.
-
-        arrowprops : `matplotlib.lines.Line2D` properties, optional
-            Dictionary of line properties for the arrow that connects
-            the annotation to the point. If the dictionnary has a key
-            `arrowstyle`, a `~matplotlib.patches.FancyArrowPatch`
-            instance is created and drawn.  See
-            `matplotlib.text.Annotation` for more details on valid
-            options. Default is None.
-
-        Returns
-        -------
-        a : `~matplotlib.text.Annotation`
-
-
-        Notes
-        -----
-
-        %(Annotation)s
-
-        Examples
-        --------
-
-        .. plot:: mpl_examples/pylab_examples/annotation_demo2.py
-        """
         a = mtext.Annotation(*args, **kwargs)
         a.set_transform(mtransforms.IdentityTransform())
         if 'clip_on' in kwargs:
             a.set_clip_path(self.patch)
         self._add_text(a)
         return a
-
+    annotate.__doc__ = mtext.Annotation.__init__.__doc__
     #### Lines and spans
 
     @docstring.dedent_interpd