Skip to content

Commit aaecec4

Browse files
tacaswelltacaswell
committed
Merge remote-tracking branch 'matplotlib/v2.1.0-doc' into v2.1.x
2 parents 4d797c7 + 10070f4 commit aaecec4

29 files changed

+496
-148
lines changed

‎.travis.yml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,10 @@ language: python
33
dist: trusty
44
sudo: false
55

6+
branches:
7+
except:
8+
- /^auto-backport-of-pr-\d*/
9+
610
cache:
711
pip: true
812
directories:

‎doc/conf.py

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -92,11 +92,11 @@ def _check_deps():
9292
autodoc_default_flags = ['members', 'undoc-members']
9393

9494
intersphinx_mapping = {
95-
'python': ('https://docs.python.org/', None),
96-
'numpy': ('https://docs.scipy.org/doc/numpy/', None),
97-
'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),
98-
'pandas': ('http://pandas.pydata.org/pandas-docs/stable', None)
99-
}
95+
'python': ('https://docs.python.org/3', None),
96+
'numpy': ('https://docs.scipy.org/doc/numpy/', None),
97+
'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),
98+
'pandas': ('https://pandas.pydata.org/pandas-docs/stable', None)
99+
}
100100

101101
explicit_order_folders = [
102102
'../examples/api',

‎doc/devel/contributing.rst

Lines changed: 19 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,8 @@ use to organize this information.
4545

4646
Thank you for your help in keeping bug reports complete, targeted and descriptive.
4747

48+
.. _installing_for_devs:
49+
4850
Retrieving and installing the latest version of the code
4951
========================================================
5052

@@ -84,17 +86,28 @@ you can use ``git@`` instead of ``https://``, which works through the ssh proto
8486
and might be easier to use if you are using 2-factor authentication.
8587

8688

87-
To make sure the tests run locally you must build against the correct version
88-
of freetype. To configure the build system to fetch and build it either export
89-
the env ``MPLLOCALFREETYPE`` as::
89+
Building Matplotlib for image comparison tests
90+
----------------------------------------------
9091

91-
export MPLLOCALFREETYPE=1
92+
Matplotlib's test suite makes heavy use of image comparison tests,
93+
meaning the result of a plot is compared against a known good result.
94+
Unfortunately, different versions of FreeType produce differently
95+
formed characters, causing these image comparisons to fail. To make
96+
them reproducible, Matplotlib can be built with a special local copy
97+
of FreeType. This is recommended for all Matplotlib developers.
9298

93-
or copy :file:`setup.cfg.template` to :file:`setup.cfg` and edit it to contain
94-
::
99+
Copy :file:`setup.cfg.template` to :file:`setup.cfg` and edit it to contain::
95100

96101
[test]
97102
local_freetype = True
103+
tests = True
104+
105+
or set the ``MPLLOCALFREETYPE`` environmental variable to any true
106+
value.
107+
108+
109+
Installing Matplotlib in developer mode
110+
---------------------------------------
98111

99112
To install Matplotlib (and compile the c-extensions) run the following
100113
command from the top-level directory ::

‎doc/devel/testing.rst

Lines changed: 7 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,10 @@ infrastructure are in :mod:`matplotlib.testing`.
2020
Requirements
2121
------------
2222

23+
Install the latest version of Matplotlib as documented in
24+
:ref:`installing_for_devs` In particular, follow the instructions to use a
25+
local FreeType build
26+
2327
The following software is required to run the tests:
2428

2529
- pytest_, version 3.0.0 or later
@@ -35,26 +39,6 @@ Optionally you can install:
3539
- pytest-xdist_ to run tests in parallel
3640

3741

38-
Building matplotlib for image comparison tests
39-
----------------------------------------------
40-
41-
matplotlib's test suite makes heavy use of image comparison tests,
42-
meaning the result of a plot is compared against a known good result.
43-
Unfortunately, different versions of FreeType produce differently
44-
formed characters, causing these image comparisons to fail. To make
45-
them reproducible, matplotlib can be built with a special local copy
46-
of FreeType. This is recommended for all matplotlib developers.
47-
48-
Add the following content to a ``setup.cfg`` file at the root of the
49-
matplotlib source directory::
50-
51-
[test]
52-
local_freetype = True
53-
tests = True
54-
55-
or by setting the ``MPLLOCALFREETYPE`` environmental variable to any true
56-
value.
57-
5842
Running the tests
5943
-----------------
6044

@@ -164,8 +148,7 @@ Writing an image based test is only slightly more difficult than a
164148
simple test. The main consideration is that you must specify the
165149
"baseline", or expected, images in the
166150
:func:`~matplotlib.testing.decorators.image_comparison` decorator. For
167-
example, this test generates a single image and automatically tests
168-
it::
151+
example, this test generates a single image and automatically tests it::
169152

170153
import numpy as np
171154
import matplotlib
@@ -262,13 +245,13 @@ repository <https://github.com/matplotlib/matplotlib/>`_ -- for
262245
example, see `its Travis page
263246
<https://travis-ci.org/matplotlib/matplotlib>`_.
264247

265-
If you want to enable Travis CI for your personal matplotlib GitHub
248+
If you want to enable Travis CI for your personal Matplotlib GitHub
266249
repo, simply enable the repo to use Travis CI in either the Travis CI
267250
UI or the GitHub UI (Admin | Service Hooks). For details, see `the
268251
Travis CI Getting Started page
269252
<https://docs.travis-ci.com/user/getting-started/>`_. This
270253
generally isn't necessary, since any pull request submitted against
271-
the main matplotlib repository will be tested.
254+
the main Matplotlib repository will be tested.
272255

273256
Once this is configured, you can see the Travis CI results at
274257
https://travis-ci.org/your_GitHub_user_name/matplotlib -- here's `an

‎doc/faq/osx_framework.rst

Lines changed: 12 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -13,16 +13,14 @@ Working with Matplotlib on OSX
1313
Introduction
1414
============
1515

16-
On OSX, two different types of Python Builds exist: a regular build and a
17-
framework build. In order to interact correctly with OSX through the native
18-
GUI frameworks you need a framework build of Python.
19-
At the time of writing the ``macosx`` and ``WXAgg`` backends require a
20-
framework build to function correctly. This can result in issues for
21-
a python installation not build as a framework and may also happen in
22-
virtual envs and when using (Ana)Conda.
23-
From Matplotlib 1.5 onwards the ``macosx`` backend
24-
checks that a framework build is available and fails if a non framework
25-
build is found. WX has a similar check build in.
16+
On OSX, two different types of Python builds exist: a regular build and a
17+
framework build. In order to interact correctly with OSX through the native
18+
GUI frameworks you need a framework build of Python. At the time of writing
19+
the ``macosx`` and ``WXAgg`` backends require a framework build to function
20+
correctly. This can result in issues for a Python installation not build as a
21+
framework and may also happen in virtual envs and when using (Ana)Conda. From
22+
Matplotlib 1.5 onwards, both backends check that a framework build is available
23+
and fail if a non framework build is found.
2624

2725
Without this check a partially functional figure is created.
2826
Among the issues with it is that it is produced in the background and
@@ -103,9 +101,9 @@ build within the virtual environment you can do ``frameworkpython -m IPython``
103101
``PYTHONHOME`` and Jupyter
104102
^^^^^^^^^^^^^^^^^^^^^^^^^^
105103

106-
This approach can be followed even if using `Jupyter <https://jupyter.org/>`_
107-
notebooks: you just need to setup a kernel with the suitable ``PYTHONHOME``
108-
definition. The `jupyter-virtualenv-osx <https://github.com/mapio/jupyter-virtualenv-osx>`_
104+
This approach can be followed even if using `Jupyter <https://jupyter.org/>`_
105+
notebooks: you just need to setup a kernel with the suitable ``PYTHONHOME``
106+
definition. The `jupyter-virtualenv-osx <https://github.com/mapio/jupyter-virtualenv-osx>`_
109107
script automates the creation of such a kernel.
110108

111109

@@ -139,7 +137,7 @@ With this in place you can run ``frameworkpython`` as above but will need to add
139137
to every virtualenv
140138

141139
PythonW Compiler
142-
^^^^^^^^^^^^^^^^
140+
----------------
143141

144142
In addition
145143
`virtualenv-pythonw-osx <https://github.com/gldnspud/virtualenv-pythonw-osx>`_

‎doc/faq/virtualenv_faq.rst

Lines changed: 0 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,6 @@
44
Working with Matplotlib in Virtual environments
55
***********************************************
66

7-
.. contents::
8-
:backlinks: none
9-
10-
.. _virtualenv_introduction:
11-
12-
Introduction
13-
============
14-
157
When running Matplotlib in a `virtual environment
168
<https://virtualenv.pypa.io/en/latest/>`_ you may discover a few issues.
179
Matplotlib itself has no issue with virtual environments. However, some of

‎doc/users/prev_whats_new/whats_new_1.5.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -109,8 +109,8 @@ You can even multiply cyclers, which is like using `itertools.product()`
109109
on two or more property cycles. Remember to use parentheses if writing
110110
a multi-line `prop_cycle` parameter.
111111

112-
.. figure:: ../../gallery/color/images/sphx_glr_color_cycle_001.png
113-
:target: ../../gallery/color/color_cycle.html
112+
.. figure:: ../../tutorials/intermediate/images/sphx_glr_color_cycle_001.png
113+
:target: ../../tutorials/intermediate/color_cycle.html
114114
:align: center
115115
:scale: 50
116116

‎examples/animation/histogram.py

Lines changed: 37 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,7 @@
33
Animated histogram
44
==================
55
6-
This example shows how to use a path patch to draw a bunch of
7-
rectangles for an animated histogram.
6+
Use a path patch to draw a bunch of rectangles for an animated histogram.
87
98
"""
109
import numpy as np
@@ -14,8 +13,6 @@
1413
import matplotlib.path as path
1514
import matplotlib.animation as animation
1615

17-
fig, ax = plt.subplots()
18-
1916
# Fixing random state for reproducibility
2017
np.random.seed(19680801)
2118

@@ -30,13 +27,23 @@
3027
top = bottom + n
3128
nrects = len(left)
3229

33-
# here comes the tricky part -- we have to set up the vertex and path
34-
# codes arrays using moveto, lineto and closepoly
35-
36-
# for each rect: 1 for the MOVETO, 3 for the LINETO, 1 for the
37-
# CLOSEPOLY; the vert for the closepoly is ignored but we still need
38-
# it to keep the codes aligned with the vertices
39-
nverts = nrects*(1 + 3 + 1)
30+
###############################################################################
31+
# Here comes the tricky part -- we have to set up the vertex and path codes
32+
# arrays using ``plt.Path.MOVETO``, ``plt.Path.LINETO`` and
33+
# ``plt.Path.CLOSEPOLY`` for each rect.
34+
#
35+
# * We need 1 ``MOVETO`` per rectangle, which sets the initial point.
36+
# * We need 3 ``LINETO``'s, which tell Matplotlib to draw lines from
37+
# vertex 1 to vertex 2, v2 to v3, and v3 to v4.
38+
# * We then need one ``CLOSEPOLY`` which tells Matplotlib to draw a line from
39+
# the v4 to our initial vertex (the ``MOVETO`` vertex), in order to close the
40+
# polygon.
41+
#
42+
# .. note::
43+
#
44+
# The vertex for ``CLOSEPOLY`` is ignored, but we still need a placeholder
45+
# in the ``verts`` array to keep the codes aligned with the vertices.
46+
nverts = nrects * (1 + 3 + 1)
4047
verts = np.zeros((nverts, 2))
4148
codes = np.ones(nverts, int) * path.Path.LINETO
4249
codes[0::5] = path.Path.MOVETO
@@ -50,13 +57,12 @@
5057
verts[3::5, 0] = right
5158
verts[3::5, 1] = bottom
5259

53-
barpath = path.Path(verts, codes)
54-
patch = patches.PathPatch(
55-
barpath, facecolor='green', edgecolor='yellow', alpha=0.5)
56-
ax.add_patch(patch)
57-
58-
ax.set_xlim(left[0], right[-1])
59-
ax.set_ylim(bottom.min(), top.max())
60+
###############################################################################
61+
# To animate the histogram, we need an ``animate`` function, which generates
62+
# a random set of numbers and updates the locations of the vertices for the
63+
# histogram (in this case, only the heights of each rectangle). ``patch`` will
64+
# eventually be a ``Patch`` object.
65+
patch = None
6066

6167

6268
def animate(i):
@@ -68,5 +74,18 @@ def animate(i):
6874
verts[2::5, 1] = top
6975
return [patch, ]
7076

77+
###############################################################################
78+
# And now we build the `Path` and `Patch` instances for the histogram using
79+
# our vertices and codes. We add the patch to the `Axes` instance, and setup
80+
# the `FuncAnimation` with our animate function.
81+
fig, ax = plt.subplots()
82+
barpath = path.Path(verts, codes)
83+
patch = patches.PathPatch(
84+
barpath, facecolor='green', edgecolor='yellow', alpha=0.5)
85+
ax.add_patch(patch)
86+
87+
ax.set_xlim(left[0], right[-1])
88+
ax.set_ylim(bottom.min(), top.max())
89+
7190
ani = animation.FuncAnimation(fig, animate, 100, repeat=False, blit=True)
7291
plt.show()

‎examples/axes_grid1/demo_axes_divider.py

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@
33
Demo Axes Divider
44
=================
55
6+
Axes divider to calculate location of axes and
7+
create a divider for them using exisiting axes instances.
68
"""
79
import matplotlib.pyplot as plt
810

‎examples/axes_grid1/demo_axes_grid.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
Demo Axes Grid
44
==============
55
6+
Grid of 2x2 images with single or own colorbar.
67
"""
78
import matplotlib.pyplot as plt
89
from mpl_toolkits.axes_grid1 import ImageGrid

‎examples/axes_grid1/demo_axes_grid2.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
Demo Axes Grid2
44
===============
55
6+
Grid of images with shared xaxis and yaxis.
67
"""
78
import matplotlib.pyplot as plt
89
from mpl_toolkits.axes_grid1 import ImageGrid

‎examples/axes_grid1/demo_axes_hbox_divider.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
Demo Axes Hbox Divider
44
======================
55
6+
Hbox Divider to arrange subplots.
67
"""
78
import numpy as np
89
import matplotlib.pyplot as plt

‎examples/axes_grid1/demo_axes_rgb.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
Demo Axes RGB
44
=============
55
6+
RGBAxes to show RGB composite images.
67
"""
78
import numpy as np
89
import matplotlib.pyplot as plt

‎examples/event_handling/poly_editor.py

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,8 @@ def draw_callback(self, event):
5959
self.background = self.canvas.copy_from_bbox(self.ax.bbox)
6060
self.ax.draw_artist(self.poly)
6161
self.ax.draw_artist(self.line)
62-
self.canvas.blit(self.ax.bbox)
62+
# do not need to blit here, this will fire before the screen is
63+
# updated
6364

6465
def poly_changed(self, poly):
6566
'this method is called whenever the polygon object is called'
@@ -114,9 +115,8 @@ def key_press_callback(self, event):
114115
elif event.key == 'd':
115116
ind = self.get_ind_under_point(event)
116117
if ind is not None:
117-
self.poly.xy = [tup
118-
for i, tup in enumerate(self.poly.xy)
119-
if i != ind]
118+
self.poly.xy = np.delete(self.poly.xy,
119+
ind, axis=0)
120120
self.line.set_data(zip(*self.poly.xy))
121121
elif event.key == 'i':
122122
xys = self.poly.get_transform().transform(self.poly.xy)
@@ -126,14 +126,14 @@ def key_press_callback(self, event):
126126
s1 = xys[i + 1]
127127
d = dist_point_to_segment(p, s0, s1)
128128
if d <= self.epsilon:
129-
self.poly.xy = np.array(
130-
list(self.poly.xy[:i]) +
131-
[(event.xdata, event.ydata)] +
132-
list(self.poly.xy[i:]))
129+
self.poly.xy = np.insert(
130+
self.poly.xy, i+1,
131+
[event.xdata, event.ydata],
132+
axis=0)
133133
self.line.set_data(zip(*self.poly.xy))
134134
break
135-
136-
self.canvas.draw()
135+
if self.line.stale:
136+
self.canvas.draw_idle()
137137

138138
def motion_notify_callback(self, event):
139139
'on mouse movement'

0 commit comments

Comments
 (0)