matplotlib · dopplershift · Mar 19, 2017 · Mar 16, 2017 · dstansby · Mar 17, 2017
diff --git a/doc/faq/howto_faq.rst b/doc/faq/howto_faq.rst
@@ -397,7 +397,7 @@ locators as desired because the two axes are independent.
 
 .. htmlonly::
 
-    See :ref:`api-two_scales` for a complete example
+    See :ref:`api-plot_two_scales` for a complete example
 
 .. _howto-batch:
 
@@ -643,7 +643,7 @@ For more on configuring your backend, see
 
 Alternatively, you can avoid pylab/pyplot altogether, which will give
 you a little more control, by calling the API directly as shown in
-:ref:`api-agg_oo`.
+:ref:`api-plot_agg_oo`.
 
 You can either generate hardcopy on the filesystem by calling savefig::
 

diff --git a/doc/users/legend_guide.rst b/doc/users/legend_guide.rst
@@ -290,7 +290,7 @@ Here is a non-exhaustive list of the examples available involving legend
 being used in various ways:
 
 * :ref:`lines_bars_and_markers-scatter_with_legend`
-* :ref:`api-legend_demo`
+* :ref:`api-plot_legend`
 * :ref:`pylab_examples-contourf_hatching`
 * :ref:`pylab_examples-figlegend_demo`
 * :ref:`pylab_examples-scatter_symbol`
diff --git a/doc/users/prev_whats_new/whats_new_1.1.rst b/doc/users/prev_whats_new/whats_new_1.1.rst
@@ -17,10 +17,11 @@ Sankey Diagrams
 
 Kevin Davies has extended Yannick Copin's original Sankey example into a module
 (:mod:`~matplotlib.sankey`) and provided new examples
-(:ref:`api-sankey_demo_basics`, :ref:`api-sankey_demo_links`,
-:ref:`api-sankey_demo_rankine`).
+(:ref:`api-plot_sankey_basics`, :ref:`api-plot_sankey_links`,
+:ref:`api-plot_sankey_rankine`).
+
+.. plot:: mpl_examples/api/plot_sankey_rankine.py
 
-.. plot:: mpl_examples/api/sankey_demo_rankine.py
 
 Animation
 ---------

diff --git a/doc/users/prev_whats_new/whats_new_1.4.rst b/doc/users/prev_whats_new/whats_new_1.4.rst
@@ -160,7 +160,7 @@ matplotlib internals were cleaned up to support using such transforms in
 :class:`~matplotlib.Axes`. This transform is important for some plot types,
 specifically the Skew-T used in meteorology.
 
-.. plot:: mpl_examples/api/skewt.py
+.. plot:: mpl_examples/api/plot_skewt.py
 
 Support for specifying properties of wedge and text in pie charts.
 ``````````````````````````````````````````````````````````````````

diff --git a/doc/users/prev_whats_new/whats_new_1.5.rst b/doc/users/prev_whats_new/whats_new_1.5.rst
@@ -367,7 +367,7 @@ kwargs names is not ideal, but `Axes.fill_between` already has a
 
 This is particularly useful for plotting pre-binned histograms.
 
-.. plot:: mpl_examples/api/filled_step.py
+.. plot:: mpl_examples/api/plot_filled_step.py
 
 
 Square Plot

diff --git a/doc/users/screenshots.rst b/doc/users/screenshots.rst
@@ -178,7 +178,7 @@ Date demo
 You can plot date data with major and minor ticks and custom tick formatters
 for both.
 
-.. plot:: mpl_examples/api/date_demo.py
+.. plot:: mpl_examples/api/plot_date.py
 
 See :mod:`matplotlib.ticker` and :mod:`matplotlib.dates` for details and usage.
 
@@ -217,7 +217,7 @@ The :func:`~matplotlib.pyplot.legend` command automatically
 generates figure legends, with MATLAB-compatible legend placement
 commands.
 
-.. plot:: mpl_examples/api/legend_demo.py
+.. plot:: mpl_examples/api/plot_legend.py
 
 Thanks to Charles Twardy for input on the legend command.
 

diff --git a/doc/users/transforms_tutorial.rst b/doc/users/transforms_tutorial.rst
@@ -452,4 +452,4 @@ best way to learn more is to open the source for those packages and
 see how to make your own, since matplotlib supports extensible axes
 and projections.  Michael Droettboom has provided a nice tutorial
 example of creating a hammer projection axes; see
-:ref:`api-custom_projection_example`.
+:ref:`api-plot_custom_projection_example`.
diff --git a/examples/api/README.txt b/examples/api/README.txt
@@ -1,39 +1,18 @@
-matplotlib API
+.. _api_examples:
+
+Matplotlib API
 ==============
 
-These examples use the matplotlib api rather than the pylab/pyplot
+These examples use the Matplotlib api rather than the pylab/pyplot
 procedural state machine.  For robust, production level scripts, or
 for applications or web application servers, we recommend you use the
-matplotlib API directly as it gives you the maximum control over your
+Matplotlib API directly as it gives you the maximum control over your
 figures, axes and plottng commands.
 
 The example agg_oo.py is the simplest example of using the Agg backend
 which is readily ported to other output formats.  This example is a
 good starting point if your are a web application developer.  Many of
-the other examples in this directory use matplotlib.pyplot just to
+the other examples in this directory use ``matplotlib.pyplot`` just to
 create the figure and show calls, and use the API for everything else.
 This is a good solution for production quality scripts.  For full
 fledged GUI applications, see the user_interfaces examples.
-
-Example style guide
-===================
-
-If you are creating new examples, you cannot import pylab or import *
-from any module in your examples.  The only three functions allowed
-from pyplot are "figure", "show" and "close", which you can use as
-convenience functions for managing figures.  All other matplotlib
-functionality must illustrate the API.
-
-A simple example of the recommended style is::
-
-    import numpy as np
-    import matplotlib.pyplot as plt
-
-    fig, ax = plt.subplots()
-    ax.plot(np.random.rand(10))
-    ax.set_xlabel('some x data')
-    ax.set_ylabel('some y data')
-    ax.set_title('some title')
-    ax.grid(True)
-    fig.savefig('myfig')
-    plt.show()
diff --git a/examples/api/demo_affine_image.py → examples/api/plot_affine_image.py b/examples/api/demo_affine_image.py → examples/api/plot_affine_image.py
diff --git a/examples/api/agg_oo.py → examples/api/plot_agg_oo.py b/examples/api/agg_oo.py → examples/api/plot_agg_oo.py
diff --git a/examples/api/barchart_demo.py → examples/api/plot_barchart.py b/examples/api/barchart_demo.py → examples/api/plot_barchart.py
diff --git a/examples/api/bbox_intersect.py → examples/api/plot_bbox_intersect.py b/examples/api/bbox_intersect.py → examples/api/plot_bbox_intersect.py
diff --git a/examples/api/collections_demo.py → examples/api/plot_collections.py b/examples/api/collections_demo.py → examples/api/plot_collections.py
diff --git a/examples/api/colorbar_basics.py → examples/api/plot_colorbar_basics.py b/examples/api/colorbar_basics.py → examples/api/plot_colorbar_basics.py
diff --git a/examples/api/colorbar_only.py → examples/api/plot_colorbar_only.py b/examples/api/colorbar_only.py → examples/api/plot_colorbar_only.py
diff --git a/examples/api/compound_path.py → examples/api/plot_compound_path.py b/examples/api/compound_path.py → examples/api/plot_compound_path.py
diff --git a/examples/api/custom_projection_example.py → ...les/api/plot_custom_projection_example.py b/examples/api/custom_projection_example.py → ...les/api/plot_custom_projection_example.py
diff --git a/examples/api/custom_scale_example.py → examples/api/plot_custom_scale_example.py b/examples/api/custom_scale_example.py → examples/api/plot_custom_scale_example.py
diff --git a/examples/api/date_demo.py → examples/api/plot_date.py b/examples/api/date_demo.py → examples/api/plot_date.py
diff --git a/examples/api/date_index_formatter.py → examples/api/plot_date_index_formatter.py b/examples/api/date_index_formatter.py → examples/api/plot_date_index_formatter.py
diff --git a/examples/api/donut_demo.py → examples/api/plot_donut.py b/examples/api/donut_demo.py → examples/api/plot_donut.py
diff --git a/examples/api/engineering_formatter.py → examples/api/plot_engineering_formatter.py b/examples/api/engineering_formatter.py → examples/api/plot_engineering_formatter.py
diff --git a/examples/api/filled_step.py → examples/api/plot_filled_step.py b/examples/api/filled_step.py → examples/api/plot_filled_step.py
diff --git a/examples/api/font_family_rc.py → examples/api/plot_font_family_rc.py b/examples/api/font_family_rc.py → examples/api/plot_font_family_rc.py
diff --git a/examples/api/font_file.py → examples/api/plot_font_file.py b/examples/api/font_file.py → examples/api/plot_font_file.py
diff --git a/examples/api/histogram_path_demo.py → examples/api/plot_histogram_path.py b/examples/api/histogram_path_demo.py → examples/api/plot_histogram_path.py
diff --git a/examples/api/image_zcoord.py → examples/api/plot_image_zcoord.py b/examples/api/image_zcoord.py → examples/api/plot_image_zcoord.py
diff --git a/examples/api/joinstyle.py → examples/api/plot_joinstyle.py b/examples/api/joinstyle.py → examples/api/plot_joinstyle.py
diff --git a/examples/api/legend_demo.py → examples/api/plot_legend.py b/examples/api/legend_demo.py → examples/api/plot_legend.py
diff --git a/examples/api/line_with_text.py → examples/api/plot_line_with_text.py b/examples/api/line_with_text.py → examples/api/plot_line_with_text.py
diff --git a/examples/api/logo2.py → examples/api/plot_logos2.py b/examples/api/logo2.py → examples/api/plot_logos2.py
diff --git a/examples/api/mathtext_asarray.py → examples/api/plot_mathtext_asarray.py b/examples/api/mathtext_asarray.py → examples/api/plot_mathtext_asarray.py
diff --git a/examples/api/patch_collection.py → examples/api/plot_patch_collection.py b/examples/api/patch_collection.py → examples/api/plot_patch_collection.py
diff --git a/examples/api/power_norm_demo.py → examples/api/plot_power_norm.py b/examples/api/power_norm_demo.py → examples/api/plot_power_norm.py
diff --git a/examples/api/quad_bezier.py → examples/api/plot_quad_bezier.py b/examples/api/quad_bezier.py → examples/api/plot_quad_bezier.py
diff --git a/examples/api/radar_chart.py → examples/api/plot_radar_chart.py b/examples/api/radar_chart.py → examples/api/plot_radar_chart.py
diff --git a/examples/api/sankey_demo_basics.py → examples/api/plot_sankey_basics.py b/examples/api/sankey_demo_basics.py → examples/api/plot_sankey_basics.py
diff --git a/examples/api/sankey_demo_links.py → examples/api/plot_sankey_links.py b/examples/api/sankey_demo_links.py → examples/api/plot_sankey_links.py
diff --git a/examples/api/sankey_demo_rankine.py → examples/api/plot_sankey_rankine.py b/examples/api/sankey_demo_rankine.py → examples/api/plot_sankey_rankine.py
diff --git a/examples/api/scatter_piecharts.py → examples/api/plot_scatter_piecharts.py b/examples/api/scatter_piecharts.py → examples/api/plot_scatter_piecharts.py
diff --git a/examples/api/skewt.py → examples/api/plot_skewt.py b/examples/api/skewt.py → examples/api/plot_skewt.py
diff --git a/examples/api/span_regions.py → examples/api/plot_span_regions.py b/examples/api/span_regions.py → examples/api/plot_span_regions.py
diff --git a/examples/api/two_scales.py → examples/api/plot_two_scales.py b/examples/api/two_scales.py → examples/api/plot_two_scales.py
diff --git a/examples/api/unicode_minus.py → examples/api/plot_unicode_minus.py b/examples/api/unicode_minus.py → examples/api/plot_unicode_minus.py
diff --git a/examples/api/watermark_image.py → examples/api/plot_watermark_image.py b/examples/api/watermark_image.py → examples/api/plot_watermark_image.py
diff --git a/examples/api/watermark_text.py → examples/api/plot_watermark_text.py b/examples/api/watermark_text.py → examples/api/plot_watermark_text.py
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -508,7 +508,7 @@ def legend(self, *args, **kwargs):
         Examples
         --------
 
-        .. plot:: mpl_examples/api/legend_demo.py
+        .. plot:: mpl_examples/api/plot_legend.py
 
         """
         handlers = kwargs.get('handler_map', {}) or {}

diff --git a/lib/matplotlib/path.py b/lib/matplotlib/path.py
@@ -318,7 +318,7 @@ def make_compound_path_from_polys(cls, XY):
         numsides x 2) numpy array of vertices.  Return object is a
         :class:`Path`
 
-        .. plot:: mpl_examples/api/histogram_path_demo.py
+        .. plot:: mpl_examples/api/plot_histogram_path.py
 
         """
 

diff --git a/lib/matplotlib/sankey.py b/lib/matplotlib/sankey.py
@@ -118,7 +118,7 @@ def __init__(self, ax=None, scale=1.0, unit='', format='%G', gap=0.25,
 
         **Examples:**
 
-            .. plot:: mpl_examples/api/sankey_demo_basics.py
+            .. plot:: mpl_examples/api/plot_sankey_basics.py
         """
         # Check the arguments.
         if gap < 0: