matplotlib · tacaswell · Jun 29, 2018 · Apr 27, 2018 · May 24, 2018 · Jun 26, 2018
diff --git a/doc/api/pyplot_summary.rst b/doc/api/pyplot_summary.rst
@@ -28,8 +28,6 @@ While it is easy to quickly generate plots with the
 we recommend using the object-oriented approach for more control
 and customization of your plots. See the methods in the
 :meth:`matplotlib.axes.Axes` class for many of the same plotting functions.
-For examples of the OO approach to Matplotlib, see the
-:ref:`API Examples<api_examples>`.
 
 Colors in Matplotlib
 --------------------

diff --git a/doc/faq/howto_faq.rst b/doc/faq/howto_faq.rst
@@ -137,7 +137,7 @@ Finally, the multipage pdf object has to be closed::
     pp.close()
 
 The same can be done using the pgf backend::
-    
+
     from matplotlib.backends.backend_pgf import PdfPages
 
 
@@ -415,7 +415,8 @@ locators as desired because the two axes are independent.
 
 .. only:: html
 
-    See :doc:`/gallery/api/two_scales` for a complete example
+    See :doc:`/gallery/subplots_axes_and_figures/two_scales` for a
+    complete example.
 
 .. _howto-batch:
 
@@ -661,7 +662,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
-:doc:`/gallery/api/agg_oo_sgskip`.
+:doc:`/gallery/misc/agg_oo_sgskip`.
 
 You can either generate hardcopy on the filesystem by calling savefig::
 

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,11 +17,12 @@ Sankey Diagrams
 
 Kevin Davies has extended Yannick Copin's original Sankey example into a module
 (:mod:`~matplotlib.sankey`) and provided new examples
-(:doc:`/gallery/api/sankey_basics`, :doc:`/gallery/api/sankey_links`,
-:doc:`/gallery/api/sankey_rankine`).
+(:doc:`/gallery/specialty_plots/sankey_basics`,
+:doc:`/gallery/specialty_plots/sankey_links`,
+:doc:`/gallery/specialty_plots/sankey_rankine`).
 
-.. figure:: ../../gallery/api/images/sphx_glr_sankey_rankine_001.png
-   :target: ../../gallery/api/sankey_rankine.html
+.. figure:: ../../gallery/specialty_plots/images/sphx_glr_sankey_rankine_001.png
+   :target: ../../gallery/specialty_plots/sankey_rankine.html
    :align: center
    :scale: 50
 

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,8 +160,8 @@ 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.
 
-.. figure:: ../../gallery/api/images/sphx_glr_skewt_001.png
-   :target: ../../gallery/api/skewt.html
+.. figure:: ../../gallery/specialty_plots/images/sphx_glr_skewt_001.png
+   :target: ../../gallery/specialty_plots/skewt.html
    :align: center
    :scale: 50
 

diff --git a/doc/users/prev_whats_new/whats_new_1.5.rst b/doc/users/prev_whats_new/whats_new_1.5.rst
@@ -377,8 +377,8 @@ kwargs names is not ideal, but `Axes.fill_between` already has a
 
 This is particularly useful for plotting pre-binned histograms.
 
-.. figure:: ../../gallery/api/images/sphx_glr_filled_step_001.png
-   :target: ../../gallery/api/filled_step.html
+.. figure:: ../../gallery/lines_bars_and_markers/images/sphx_glr_filled_step_001.png
+   :target: ../../gallery/lines_bars_and_markers/filled_step.html
    :align: center
    :scale: 50
 

diff --git a/examples/README b/examples/README
@@ -16,8 +16,6 @@ Below is a brief description of the different directories found here:
   * animation - Dynamic plots, see the documentation at
     http://matplotlib.org/api/animation_api.html
 
-  * api - working with the Matplotlib API directly.
-
   * axes_grid1 - Examples related to the axes_grid1 toolkit.
 
   * axisartist - Examples related to the axisartist toolkit.

diff --git a/examples/api/README.txt b/examples/api/README.txt
diff --git a/examples/api/image_zcoord.py → ...mages_contours_and_fields/image_zcoord.py b/examples/api/image_zcoord.py → ...mages_contours_and_fields/image_zcoord.py
diff --git a/examples/api/watermark_image.py → ...es_contours_and_fields/watermark_image.py b/examples/api/watermark_image.py → ...es_contours_and_fields/watermark_image.py
@@ -3,7 +3,7 @@
 Watermark image
 ===============
 
-Use a PNG file as a watermark
+Using a PNG file as a watermark.
 """
 import numpy as np
 import matplotlib.cbook as cbook

diff --git a/examples/api/filled_step.py → ...les/lines_bars_and_markers/filled_step.py b/examples/api/filled_step.py → ...les/lines_bars_and_markers/filled_step.py
diff --git a/examples/api/joinstyle.py → examples/lines_bars_and_markers/joinstyle.py b/examples/api/joinstyle.py → examples/lines_bars_and_markers/joinstyle.py
diff --git a/examples/api/scatter_piecharts.py → ...nes_bars_and_markers/scatter_piecharts.py b/examples/api/scatter_piecharts.py → ...nes_bars_and_markers/scatter_piecharts.py
diff --git a/examples/api/span_regions.py → ...es/lines_bars_and_markers/span_regions.py b/examples/api/span_regions.py → ...es/lines_bars_and_markers/span_regions.py
@@ -4,7 +4,7 @@
 ================
 
 Illustrate some helper functions for shading regions where a logical
-mask is True
+mask is True.
 
 See :meth:`matplotlib.collections.BrokenBarHCollection.span_where`
 """

diff --git a/examples/api/agg_oo_sgskip.py → examples/misc/agg_oo_sgskip.py b/examples/api/agg_oo_sgskip.py → examples/misc/agg_oo_sgskip.py
diff --git a/examples/api/histogram_path.py → examples/misc/histogram_path.py b/examples/api/histogram_path.py → examples/misc/histogram_path.py
diff --git a/examples/api/logos2.py → examples/misc/logos2.py b/examples/api/logos2.py → examples/misc/logos2.py
diff --git a/examples/api/power_norm.py → examples/scales/power_norm.py b/examples/api/power_norm.py → examples/scales/power_norm.py
diff --git a/examples/api/patch_collection.py → ...hapes_and_collections/patch_collection.py b/examples/api/patch_collection.py → ...hapes_and_collections/patch_collection.py
diff --git a/examples/api/quad_bezier.py → ...les/shapes_and_collections/quad_bezier.py b/examples/api/quad_bezier.py → ...les/shapes_and_collections/quad_bezier.py
diff --git a/examples/api/radar_chart.py → examples/specialty_plots/radar_chart.py b/examples/api/radar_chart.py → examples/specialty_plots/radar_chart.py
diff --git a/examples/api/sankey_basics.py → examples/specialty_plots/sankey_basics.py b/examples/api/sankey_basics.py → examples/specialty_plots/sankey_basics.py
diff --git a/examples/api/sankey_links.py → examples/specialty_plots/sankey_links.py b/examples/api/sankey_links.py → examples/specialty_plots/sankey_links.py
diff --git a/examples/api/sankey_rankine.py → examples/specialty_plots/sankey_rankine.py b/examples/api/sankey_rankine.py → examples/specialty_plots/sankey_rankine.py
diff --git a/examples/api/skewt.py → examples/specialty_plots/skewt.py b/examples/api/skewt.py → examples/specialty_plots/skewt.py
diff --git a/examples/api/two_scales.py → ...s/subplots_axes_and_figures/two_scales.py b/examples/api/two_scales.py → ...s/subplots_axes_and_figures/two_scales.py
@@ -3,8 +3,7 @@
 Plots with different scales
 ===========================
 
-Demonstrate how to do two plots on the same axes with different left and
-right scales.
+Two plots on the same axes with different left and right scales.
 
 The trick is to use *two different axes* that share the same *x* axis.
 You can use separate `matplotlib.ticker` formatters and locators as

diff --git a/examples/test2.png b/examples/test2.png
diff --git a/examples/api/font_family_rc_sgskip.py → ..._and_annotations/font_family_rc_sgskip.py b/examples/api/font_family_rc_sgskip.py → ..._and_annotations/font_family_rc_sgskip.py
diff --git a/examples/api/font_file.py → .../text_labels_and_annotations/font_file.py b/examples/api/font_file.py → .../text_labels_and_annotations/font_file.py
@@ -10,7 +10,8 @@
 Here, we use the Computer Modern roman font (``cmr10``) shipped with
 Matplotlib.
 
-For a more flexible solution, see :doc:`/gallery/api/font_family_rc_sgskip` and
+For a more flexible solution, see
+:doc:`/gallery/text_labels_and_annotations/font_family_rc_sgskip` and
 :doc:`/gallery/text_labels_and_annotations/fonts_demo`.
 """
 

diff --git a/examples/api/legend.py → ...les/text_labels_and_annotations/legend.py b/examples/api/legend.py → ...les/text_labels_and_annotations/legend.py
@@ -24,7 +24,7 @@
 legend = ax.legend(loc='upper center', shadow=True, fontsize='x-large')
 
 # Put a nicer background color on the legend.
-legend.get_frame().set_facecolor('#00FFCC')
+legend.get_frame().set_facecolor('C0')
 
 plt.show()
 

diff --git a/examples/api/line_with_text.py → ..._labels_and_annotations/line_with_text.py b/examples/api/line_with_text.py → ..._labels_and_annotations/line_with_text.py
diff --git a/examples/api/mathtext_asarray.py → ...abels_and_annotations/mathtext_asarray.py b/examples/api/mathtext_asarray.py → ...abels_and_annotations/mathtext_asarray.py
diff --git a/examples/api/unicode_minus.py → ...t_labels_and_annotations/unicode_minus.py b/examples/api/unicode_minus.py → ...t_labels_and_annotations/unicode_minus.py
diff --git a/examples/api/watermark_text.py → ..._labels_and_annotations/watermark_text.py b/examples/api/watermark_text.py → ..._labels_and_annotations/watermark_text.py
@@ -3,12 +3,9 @@
 Text watermark
 ==============
 
-Use a Text as a watermark
+Adding a text watermark.
 """
 import numpy as np
-#import matplotlib
-#matplotlib.use('Agg')
-
 import matplotlib.pyplot as plt
 
 # Fixing random state for reproducibility
@@ -19,7 +16,6 @@
 ax.plot(np.random.rand(20), '-o', ms=20, lw=2, alpha=0.7, mfc='orange')
 ax.grid()
 
-# position bottom right
 fig.text(0.95, 0.05, 'Property of MPL',
          fontsize=50, color='gray',
          ha='right', va='bottom', alpha=0.5)

diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -368,7 +368,7 @@ def legend(self, *args, **kwargs):
         Examples
         --------
 
-        .. plot:: gallery/api/legend.py
+        .. plot:: gallery/text_labels_and_annotations/legend.py
 
         """
         handles, labels, extra_args, kwargs = mlegend._parse_legend_args(

diff --git a/lib/matplotlib/path.py b/lib/matplotlib/path.py
@@ -303,7 +303,7 @@ def make_compound_path_from_polys(cls, XY):
         numsides x 2) numpy array of vertices.  Return object is a
         :class:`Path`
 
-        .. plot:: gallery/api/histogram_path.py
+        .. plot:: gallery/misc/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:: gallery/api/sankey_basics.py
+            .. plot:: gallery/specialty_plots/sankey_basics.py
         """
         # Check the arguments.
         if gap < 0:

diff --git a/tutorials/introductory/lifecycle.py b/tutorials/introductory/lifecycle.py
@@ -36,9 +36,7 @@
   "axis", which refers to the x/y axis of a plot).
 
 We call methods that do the plotting directly from the Axes, which gives
-us much more flexibility and power in customizing our plot. See the
-:ref:`object-oriented examples <api_examples>` for many examples of how
-this approach is used.
+us much more flexibility and power in customizing our plot.
 
 .. note::
 

diff --git a/tutorials/introductory/sample_plots.py b/tutorials/introductory/sample_plots.py
@@ -333,8 +333,8 @@
 generates figure legends, with MATLAB-compatible legend-placement
 functions.
 
-.. figure:: ../../gallery/api/images/sphx_glr_legend_001.png
-   :target: ../../gallery/api/legend.html
+.. figure:: ../../gallery/text_labels_and_annotations/images/sphx_glr_legend_001.png
+   :target: ../../gallery/text_labels_and_annotations/legend.html
    :align: center
    :scale: 50