From a17c6a1f85f70dd06d78a7d1fa5f76831beb41d9 Mon Sep 17 00:00:00 2001
From: Nelle Varoquaux <nelle.varoquaux@gmail.com>
Date: Thu, 16 Mar 2017 16:33:05 -0700
Subject: [PATCH] DOC api's transition to sphinx-gallery is now complete

---
 doc/faq/howto_faq.rst                         |  4 +--
 doc/users/legend_guide.rst                    |  2 +-
 doc/users/prev_whats_new/whats_new_1.1.rst    |  7 ++--
 doc/users/prev_whats_new/whats_new_1.4.rst    |  2 +-
 doc/users/prev_whats_new/whats_new_1.5.rst    |  2 +-
 doc/users/screenshots.rst                     |  4 +--
 doc/users/transforms_tutorial.rst             |  2 +-
 examples/api/README.txt                       | 33 ++++---------------
 ...o_affine_image.py => plot_affine_image.py} |  0
 examples/api/{agg_oo.py => plot_agg_oo.py}    |  0
 .../{barchart_demo.py => plot_barchart.py}    |  0
 ...ox_intersect.py => plot_bbox_intersect.py} |  0
 ...ollections_demo.py => plot_collections.py} |  0
 ...rbar_basics.py => plot_colorbar_basics.py} |  0
 ...colorbar_only.py => plot_colorbar_only.py} |  0
 ...compound_path.py => plot_compound_path.py} |  0
 ...e.py => plot_custom_projection_example.py} |  0
 ...xample.py => plot_custom_scale_example.py} |  0
 examples/api/{date_demo.py => plot_date.py}   |  0
 ...matter.py => plot_date_index_formatter.py} |  0
 examples/api/{donut_demo.py => plot_donut.py} |  0
 ...atter.py => plot_engineering_formatter.py} |  0
 .../{filled_step.py => plot_filled_step.py}   |  0
 ...nt_family_rc.py => plot_font_family_rc.py} |  0
 .../api/{font_file.py => plot_font_file.py}   |  0
 ...am_path_demo.py => plot_histogram_path.py} |  0
 .../{image_zcoord.py => plot_image_zcoord.py} |  0
 .../api/{joinstyle.py => plot_joinstyle.py}   |  0
 .../api/{legend_demo.py => plot_legend.py}    |  0
 ...ne_with_text.py => plot_line_with_text.py} |  0
 examples/api/{logo2.py => plot_logos2.py}     |  0
 ...xt_asarray.py => plot_mathtext_asarray.py} |  0
 ...collection.py => plot_patch_collection.py} |  0
 ...{power_norm_demo.py => plot_power_norm.py} |  0
 .../{quad_bezier.py => plot_quad_bezier.py}   |  0
 .../{radar_chart.py => plot_radar_chart.py}   |  0
 ...y_demo_basics.py => plot_sankey_basics.py} |  0
 ...key_demo_links.py => plot_sankey_links.py} |  0
 ...demo_rankine.py => plot_sankey_rankine.py} |  0
 ...piecharts.py => plot_scatter_piecharts.py} |  0
 examples/api/{skewt.py => plot_skewt.py}      |  0
 .../{span_regions.py => plot_span_regions.py} |  0
 .../api/{two_scales.py => plot_two_scales.py} |  0
 ...unicode_minus.py => plot_unicode_minus.py} |  0
 ...rmark_image.py => plot_watermark_image.py} |  0
 ...termark_text.py => plot_watermark_text.py} |  0
 lib/matplotlib/axes/_axes.py                  |  2 +-
 lib/matplotlib/path.py                        |  2 +-
 lib/matplotlib/sankey.py                      |  2 +-
 49 files changed, 21 insertions(+), 41 deletions(-)
 rename examples/api/{demo_affine_image.py => plot_affine_image.py} (100%)
 rename examples/api/{agg_oo.py => plot_agg_oo.py} (100%)
 rename examples/api/{barchart_demo.py => plot_barchart.py} (100%)
 rename examples/api/{bbox_intersect.py => plot_bbox_intersect.py} (100%)
 rename examples/api/{collections_demo.py => plot_collections.py} (100%)
 rename examples/api/{colorbar_basics.py => plot_colorbar_basics.py} (100%)
 rename examples/api/{colorbar_only.py => plot_colorbar_only.py} (100%)
 rename examples/api/{compound_path.py => plot_compound_path.py} (100%)
 rename examples/api/{custom_projection_example.py => plot_custom_projection_example.py} (100%)
 rename examples/api/{custom_scale_example.py => plot_custom_scale_example.py} (100%)
 rename examples/api/{date_demo.py => plot_date.py} (100%)
 rename examples/api/{date_index_formatter.py => plot_date_index_formatter.py} (100%)
 rename examples/api/{donut_demo.py => plot_donut.py} (100%)
 rename examples/api/{engineering_formatter.py => plot_engineering_formatter.py} (100%)
 rename examples/api/{filled_step.py => plot_filled_step.py} (100%)
 rename examples/api/{font_family_rc.py => plot_font_family_rc.py} (100%)
 rename examples/api/{font_file.py => plot_font_file.py} (100%)
 rename examples/api/{histogram_path_demo.py => plot_histogram_path.py} (100%)
 rename examples/api/{image_zcoord.py => plot_image_zcoord.py} (100%)
 rename examples/api/{joinstyle.py => plot_joinstyle.py} (100%)
 rename examples/api/{legend_demo.py => plot_legend.py} (100%)
 rename examples/api/{line_with_text.py => plot_line_with_text.py} (100%)
 rename examples/api/{logo2.py => plot_logos2.py} (100%)
 rename examples/api/{mathtext_asarray.py => plot_mathtext_asarray.py} (100%)
 rename examples/api/{patch_collection.py => plot_patch_collection.py} (100%)
 rename examples/api/{power_norm_demo.py => plot_power_norm.py} (100%)
 rename examples/api/{quad_bezier.py => plot_quad_bezier.py} (100%)
 rename examples/api/{radar_chart.py => plot_radar_chart.py} (100%)
 rename examples/api/{sankey_demo_basics.py => plot_sankey_basics.py} (100%)
 rename examples/api/{sankey_demo_links.py => plot_sankey_links.py} (100%)
 rename examples/api/{sankey_demo_rankine.py => plot_sankey_rankine.py} (100%)
 rename examples/api/{scatter_piecharts.py => plot_scatter_piecharts.py} (100%)
 rename examples/api/{skewt.py => plot_skewt.py} (100%)
 rename examples/api/{span_regions.py => plot_span_regions.py} (100%)
 rename examples/api/{two_scales.py => plot_two_scales.py} (100%)
 rename examples/api/{unicode_minus.py => plot_unicode_minus.py} (100%)
 rename examples/api/{watermark_image.py => plot_watermark_image.py} (100%)
 rename examples/api/{watermark_text.py => plot_watermark_text.py} (100%)

diff --git a/doc/faq/howto_faq.rst b/doc/faq/howto_faq.rst
index 5dd9f9fbc61f..210903ea10a9 100644
--- 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
index 3c204a640e90..c7fb0621df9f 100644
--- 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
index 8002e830d2e7..54cd72d80063 100644
--- 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
index d2e35a5cefa5..51b377f0ee05 100644
--- 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
index a9fd1e83f4e7..a8edf5c3b2db 100644
--- 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
index 1e7b4dbed6be..d5ab16bb7870 100644
--- 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
index fc3e574f190a..767ce5f428b9 100644
--- 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
index a0b901f9d20c..c0359dc24319 100644
--- 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 b/examples/api/plot_affine_image.py
similarity index 100%
rename from examples/api/demo_affine_image.py
rename to examples/api/plot_affine_image.py
diff --git a/examples/api/agg_oo.py b/examples/api/plot_agg_oo.py
similarity index 100%
rename from examples/api/agg_oo.py
rename to examples/api/plot_agg_oo.py
diff --git a/examples/api/barchart_demo.py b/examples/api/plot_barchart.py
similarity index 100%
rename from examples/api/barchart_demo.py
rename to examples/api/plot_barchart.py
diff --git a/examples/api/bbox_intersect.py b/examples/api/plot_bbox_intersect.py
similarity index 100%
rename from examples/api/bbox_intersect.py
rename to examples/api/plot_bbox_intersect.py
diff --git a/examples/api/collections_demo.py b/examples/api/plot_collections.py
similarity index 100%
rename from examples/api/collections_demo.py
rename to examples/api/plot_collections.py
diff --git a/examples/api/colorbar_basics.py b/examples/api/plot_colorbar_basics.py
similarity index 100%
rename from examples/api/colorbar_basics.py
rename to examples/api/plot_colorbar_basics.py
diff --git a/examples/api/colorbar_only.py b/examples/api/plot_colorbar_only.py
similarity index 100%
rename from examples/api/colorbar_only.py
rename to examples/api/plot_colorbar_only.py
diff --git a/examples/api/compound_path.py b/examples/api/plot_compound_path.py
similarity index 100%
rename from examples/api/compound_path.py
rename to examples/api/plot_compound_path.py
diff --git a/examples/api/custom_projection_example.py b/examples/api/plot_custom_projection_example.py
similarity index 100%
rename from examples/api/custom_projection_example.py
rename to examples/api/plot_custom_projection_example.py
diff --git a/examples/api/custom_scale_example.py b/examples/api/plot_custom_scale_example.py
similarity index 100%
rename from examples/api/custom_scale_example.py
rename to examples/api/plot_custom_scale_example.py
diff --git a/examples/api/date_demo.py b/examples/api/plot_date.py
similarity index 100%
rename from examples/api/date_demo.py
rename to examples/api/plot_date.py
diff --git a/examples/api/date_index_formatter.py b/examples/api/plot_date_index_formatter.py
similarity index 100%
rename from examples/api/date_index_formatter.py
rename to examples/api/plot_date_index_formatter.py
diff --git a/examples/api/donut_demo.py b/examples/api/plot_donut.py
similarity index 100%
rename from examples/api/donut_demo.py
rename to examples/api/plot_donut.py
diff --git a/examples/api/engineering_formatter.py b/examples/api/plot_engineering_formatter.py
similarity index 100%
rename from examples/api/engineering_formatter.py
rename to examples/api/plot_engineering_formatter.py
diff --git a/examples/api/filled_step.py b/examples/api/plot_filled_step.py
similarity index 100%
rename from examples/api/filled_step.py
rename to examples/api/plot_filled_step.py
diff --git a/examples/api/font_family_rc.py b/examples/api/plot_font_family_rc.py
similarity index 100%
rename from examples/api/font_family_rc.py
rename to examples/api/plot_font_family_rc.py
diff --git a/examples/api/font_file.py b/examples/api/plot_font_file.py
similarity index 100%
rename from examples/api/font_file.py
rename to examples/api/plot_font_file.py
diff --git a/examples/api/histogram_path_demo.py b/examples/api/plot_histogram_path.py
similarity index 100%
rename from examples/api/histogram_path_demo.py
rename to examples/api/plot_histogram_path.py
diff --git a/examples/api/image_zcoord.py b/examples/api/plot_image_zcoord.py
similarity index 100%
rename from examples/api/image_zcoord.py
rename to examples/api/plot_image_zcoord.py
diff --git a/examples/api/joinstyle.py b/examples/api/plot_joinstyle.py
similarity index 100%
rename from examples/api/joinstyle.py
rename to examples/api/plot_joinstyle.py
diff --git a/examples/api/legend_demo.py b/examples/api/plot_legend.py
similarity index 100%
rename from examples/api/legend_demo.py
rename to examples/api/plot_legend.py
diff --git a/examples/api/line_with_text.py b/examples/api/plot_line_with_text.py
similarity index 100%
rename from examples/api/line_with_text.py
rename to examples/api/plot_line_with_text.py
diff --git a/examples/api/logo2.py b/examples/api/plot_logos2.py
similarity index 100%
rename from examples/api/logo2.py
rename to examples/api/plot_logos2.py
diff --git a/examples/api/mathtext_asarray.py b/examples/api/plot_mathtext_asarray.py
similarity index 100%
rename from examples/api/mathtext_asarray.py
rename to examples/api/plot_mathtext_asarray.py
diff --git a/examples/api/patch_collection.py b/examples/api/plot_patch_collection.py
similarity index 100%
rename from examples/api/patch_collection.py
rename to examples/api/plot_patch_collection.py
diff --git a/examples/api/power_norm_demo.py b/examples/api/plot_power_norm.py
similarity index 100%
rename from examples/api/power_norm_demo.py
rename to examples/api/plot_power_norm.py
diff --git a/examples/api/quad_bezier.py b/examples/api/plot_quad_bezier.py
similarity index 100%
rename from examples/api/quad_bezier.py
rename to examples/api/plot_quad_bezier.py
diff --git a/examples/api/radar_chart.py b/examples/api/plot_radar_chart.py
similarity index 100%
rename from examples/api/radar_chart.py
rename to examples/api/plot_radar_chart.py
diff --git a/examples/api/sankey_demo_basics.py b/examples/api/plot_sankey_basics.py
similarity index 100%
rename from examples/api/sankey_demo_basics.py
rename to examples/api/plot_sankey_basics.py
diff --git a/examples/api/sankey_demo_links.py b/examples/api/plot_sankey_links.py
similarity index 100%
rename from examples/api/sankey_demo_links.py
rename to examples/api/plot_sankey_links.py
diff --git a/examples/api/sankey_demo_rankine.py b/examples/api/plot_sankey_rankine.py
similarity index 100%
rename from examples/api/sankey_demo_rankine.py
rename to examples/api/plot_sankey_rankine.py
diff --git a/examples/api/scatter_piecharts.py b/examples/api/plot_scatter_piecharts.py
similarity index 100%
rename from examples/api/scatter_piecharts.py
rename to examples/api/plot_scatter_piecharts.py
diff --git a/examples/api/skewt.py b/examples/api/plot_skewt.py
similarity index 100%
rename from examples/api/skewt.py
rename to examples/api/plot_skewt.py
diff --git a/examples/api/span_regions.py b/examples/api/plot_span_regions.py
similarity index 100%
rename from examples/api/span_regions.py
rename to examples/api/plot_span_regions.py
diff --git a/examples/api/two_scales.py b/examples/api/plot_two_scales.py
similarity index 100%
rename from examples/api/two_scales.py
rename to examples/api/plot_two_scales.py
diff --git a/examples/api/unicode_minus.py b/examples/api/plot_unicode_minus.py
similarity index 100%
rename from examples/api/unicode_minus.py
rename to examples/api/plot_unicode_minus.py
diff --git a/examples/api/watermark_image.py b/examples/api/plot_watermark_image.py
similarity index 100%
rename from examples/api/watermark_image.py
rename to examples/api/plot_watermark_image.py
diff --git a/examples/api/watermark_text.py b/examples/api/plot_watermark_text.py
similarity index 100%
rename from examples/api/watermark_text.py
rename to examples/api/plot_watermark_text.py
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
index c7497d8997c4..59553ed59f4b 100644
--- 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
index 73754f069ad9..bbaf61f8d5de 100644
--- 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
index 2269d63d4d51..b5f8fb51696a 100644
--- 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: