matplotlib · QuLogic · Nov 3, 2020 · Nov 1, 2020 · timhoffm · Nov 1, 2020
diff --git a/examples/axisartist/demo_ticklabel_alignment.py b/examples/axisartist/demo_ticklabel_alignment.py
@@ -1,7 +1,7 @@
 """
-========================
-Demo Ticklabel Alignment
-========================
+===================
+Ticklabel alignment
+===================
 
 """
 

diff --git a/examples/axisartist/demo_ticklabel_direction.py b/examples/axisartist/demo_ticklabel_direction.py
@@ -1,7 +1,7 @@
 """
-========================
-Demo Ticklabel Direction
-========================
+===================
+Ticklabel direction
+===================
 
 """
 

diff --git a/examples/event_handling/coords_demo.py b/examples/event_handling/coords_demo.py
@@ -1,7 +1,7 @@
 """
-===========
-Coords demo
-===========
+===========================
+Mouse move and click events
+===========================
 
 An example of how to interact with the plotting canvas by connecting to move
 and click events.

diff --git a/examples/event_handling/figure_axes_enter_leave.py b/examples/event_handling/figure_axes_enter_leave.py
@@ -1,10 +1,10 @@
 """
-=======================
-Figure Axes Enter Leave
-=======================
+==================================
+Figure/Axes enter and leave events
+==================================
 
-Illustrate the figure and axes enter and leave events by changing the
-frame colors on enter and leave
+Illustrate the figure and Axes enter and leave events by changing the
+frame colors on enter and leave.
 """
 import matplotlib.pyplot as plt
 
@@ -32,24 +32,13 @@ def on_leave_figure(event):
     event.canvas.figure.patch.set_facecolor('grey')
     event.canvas.draw()
 
-###############################################################################
 
-fig1, (ax, ax2) = plt.subplots(2, 1)
-fig1.suptitle('mouse hover over figure or axes to trigger events')
+fig, axs = plt.subplots(2, 1)
+fig.suptitle('mouse hover over figure or axes to trigger events')
 
-fig1.canvas.mpl_connect('figure_enter_event', on_enter_figure)
-fig1.canvas.mpl_connect('figure_leave_event', on_leave_figure)
-fig1.canvas.mpl_connect('axes_enter_event', on_enter_axes)
-fig1.canvas.mpl_connect('axes_leave_event', on_leave_axes)
-
-###############################################################################
-
-fig2, (ax, ax2) = plt.subplots(2, 1)
-fig2.suptitle('mouse hover over figure or axes to trigger events')
-
-fig2.canvas.mpl_connect('figure_enter_event', on_enter_figure)
-fig2.canvas.mpl_connect('figure_leave_event', on_leave_figure)
-fig2.canvas.mpl_connect('axes_enter_event', on_enter_axes)
-fig2.canvas.mpl_connect('axes_leave_event', on_leave_axes)
+fig.canvas.mpl_connect('figure_enter_event', on_enter_figure)
+fig.canvas.mpl_connect('figure_leave_event', on_leave_figure)
+fig.canvas.mpl_connect('axes_enter_event', on_enter_axes)
+fig.canvas.mpl_connect('axes_leave_event', on_leave_axes)
 
 plt.show()
diff --git a/examples/event_handling/keypress_demo.py b/examples/event_handling/keypress_demo.py
@@ -1,9 +1,9 @@
 """
-=============
-Keypress Demo
-=============
+==============
+Keypress event
+==============
 
-Show how to connect to keypress events
+Show how to connect to keypress events.
 """
 import sys
 import numpy as np
@@ -18,10 +18,10 @@ def on_press(event):
         xl.set_visible(not visible)
         fig.canvas.draw()
 
+
 # Fixing random state for reproducibility
 np.random.seed(19680801)
 
-
 fig, ax = plt.subplots()
 
 fig.canvas.mpl_connect('key_press_event', on_press)

diff --git a/examples/misc/demo_agg_filter.py b/examples/misc/demo_agg_filter.py
@@ -1,8 +1,13 @@
 """
-===============
-Demo Agg Filter
-===============
+==========
+AGG filter
+==========
 
+Most pixel-based backends in Matplotlib use `Anti-Grain Geometry (AGG)`_ for
+rendering. You can modify the rendering of Artists by applying a filter via
+`.Artist.set_agg_filter`.
+
+.. _Anti-Grain Geometry (AGG): http://antigrain.com
 """
 
 import matplotlib.cm as cm

diff --git a/examples/pie_and_polar_charts/polar_demo.py b/examples/pie_and_polar_charts/polar_demo.py
@@ -1,6 +1,6 @@
 """
 ==========
-Polar Demo
+Polar plot
 ==========
 
 Demo of a line plot on a polar axis.

diff --git a/examples/subplots_axes_and_figures/axis_equal_demo.py b/examples/subplots_axes_and_figures/axis_equal_demo.py
@@ -1,9 +1,9 @@
 """
-===============
-Axis Equal Demo
-===============
+=======================
+Equal axis aspect ratio
+=======================
 
-How to set and adjust plots with equal axis ratios.
+How to set and adjust plots with equal axis aspect ratios.
 """
 
 import matplotlib.pyplot as plt

diff --git a/examples/subplots_axes_and_figures/multiple_figs_demo.py b/examples/subplots_axes_and_figures/multiple_figs_demo.py
@@ -1,9 +1,20 @@
 """
-==================
-Multiple Figs Demo
-==================
+===================================
+Managing multiple figures in pyplot
+===================================
+
+`matplotlib.pyplot` uses the concept of a *current figure* and *current axes*.
+Figures are identified via a figure number that is passed to `~.pyplot.figure`.
+The figure with the given number is set as *current figure*. Additionally, if
+no figure with the number exists, a new one is created.
+
+.. note::
+
+    We discourage working with multiple figures in pyplot because managing
+    the *current figure* is cumbersome and error-prone. Instead, we recommend
+    to use the object-oriented approach and call methods on Figure and Axes
+    instances.
 
-Working with multiple figure windows and subplots
 """
 import matplotlib.pyplot as plt
 import numpy as np

diff --git a/examples/subplots_axes_and_figures/shared_axis_demo.py b/examples/subplots_axes_and_figures/shared_axis_demo.py
@@ -1,10 +1,10 @@
 """
-================
-Shared Axis Demo
-================
+===========
+Shared Axis
+===========
 
 You can share the x or y axis limits for one axis with another by
-passing an axes instance as a sharex or sharey kwarg.
+passing an axes instance as a *sharex* or *sharey* keyword argument.
 
 Changing the axis limits on one axes will be reflected automatically
 in the other, and vice-versa, so when you navigate with the toolbar