matplotlib · NelleV · Aug 4, 2017 · Aug 1, 2017 · Aug 2, 2017 · Aug 4, 2017
diff --git a/doc-requirements.txt b/doc-requirements.txt
@@ -13,4 +13,4 @@ mock
 numpydoc
 pillow
 scipy
-sphinx-gallery
+sphinx-gallery>=0.1.12
diff --git a/doc/_templates/index.html b/doc/_templates/index.html
@@ -55,7 +55,7 @@ <h1>Introduction</h1>
   interface toolkits.</p>
 
   <div class="responsive_screenshots">
-    <a a href="{{ pathto('tutorials/01_introductory/sample_plots') }}">
+    <a a href="{{ pathto('tutorials/introductory/sample_plots') }}">
       <div class="responsive_subfig">
         <img align="middle", src="{{ pathto('_images/sphx_glr_membrane_thumb.png', 1) }}", border="0", alt="screenshots"/>
       </div>
@@ -75,7 +75,7 @@ <h1>Introduction</h1>
   <p>Matplotlib tries to make easy things easy and hard things possible.
   You can generate plots, histograms, power spectra, bar charts,
   errorcharts, scatterplots, etc., with just a few lines of code.
-  For examples, see the <a href="{{ pathto('tutorials/01_introductory/sample_plots')
+  For examples, see the <a href="{{ pathto('tutorials/introductory/sample_plots')
   }}">sample plots</a> and <a href="{{ pathto('gallery/index') }}">thumbnail</a> gallery.</p>
 
 <p>For simple plotting the <tt>pyplot</tt> module provides a

diff --git a/doc/api/api_changes.rst b/doc/api/api_changes.rst
@@ -821,7 +821,7 @@ original location:
 * The legend handler interface has changed from a callable, to any object
   which implements the ``legend_artists`` method (a deprecation phase will
   see this interface be maintained for v1.4). See
-  :ref:`sphx_glr_tutorials_02_intermediate_legend_guide.py` for further details. Further legend changes
+  :ref:`sphx_glr_tutorials_intermediate_legend_guide.py` for further details. Further legend changes
   include:
 
    * :func:`matplotlib.axes.Axes._get_legend_handles` now returns a generator

diff --git a/doc/api/pyplot_summary.rst b/doc/api/pyplot_summary.rst
@@ -8,7 +8,7 @@ The Pyplot API
 The :mod:`matplotlib.pyplot` module contains functions that allow you to generate
 many kinds of plots quickly. For examples that showcase the use
 of the :mod:`matplotlib.pyplot` module, see the
-:ref:`sphx_glr_tutorials_01_introductory_pyplot.py`
+:ref:`sphx_glr_tutorials_introductory_pyplot.py`
 or the :ref:`pyplots_examples`. We also recommend that you look into
 the object-oriented approach to plotting, described below.
 

diff --git a/doc/conf.py b/doc/conf.py
@@ -15,6 +15,8 @@
 import sys
 import sphinx
 import six
+from glob import glob
+from sphinx_gallery.sorting import ExplicitOrder
 
 # If your extensions are in another directory, add it here. If the directory
 # is relative to the documentation root, use os.path.abspath to make it
@@ -95,6 +97,27 @@ def _check_deps():
   'pandas': ('http://pandas.pydata.org/pandas-docs/stable', None)
   }
 
+explicit_order_folders = [
+                          '../examples/api',
+                          '../examples/pyplots',
+                          '../examples/subplots_axes_and_figures',
+                          '../examples/color',
+                          '../examples/statistics',
+                          '../examples/lines_bars_and_markers',
+                          '../examples/images_contours_and_fields',
+                          '../examples/shapes_and_collections',
+                          '../examples/text_labels_and_annotations',
+                          '../examples/pie_and_polar_charts',
+                          '../examples/style_sheets',
+                          '../examples/axes_grid',
+                          '../examples/showcase',
+                          '../tutorials/introductory',
+                          '../tutorials/intermediate',
+                          '../tutorials/advanced']
+for folder in sorted(glob('../examples/*') + glob('../tutorials/*')):
+    if not os.path.isdir(folder) or folder in explicit_order_folders:
+        continue
+    explicit_order_folders.append(folder)
 
 # Sphinx gallery configuration
 sphinx_gallery_conf = {
@@ -107,7 +130,8 @@ def _check_deps():
         'numpy': 'https://docs.scipy.org/doc/numpy',
         'scipy': 'https://docs.scipy.org/doc/scipy/reference',
     },
-    'backreferences_dir': 'api/_as_gen'
+    'backreferences_dir': 'api/_as_gen',
+    'subsection_order': ExplicitOrder(explicit_order_folders)
 }
 
 plot_gallery = True

diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst
@@ -14,7 +14,7 @@ Submitting a bug report
 
 If you find a bug in the code or documentation, do not hesitate to submit a
 ticket to the
-`Bug Tracker <https://github.com/matplotlib/matplotlib/issues>`_. You are also 
+`Bug Tracker <https://github.com/matplotlib/matplotlib/issues>`_. You are also
 welcome to post feature requests or pull requests.
 
 If you are reporting a bug, please do your best to include the following:
@@ -23,7 +23,7 @@ If you are reporting a bug, please do your best to include the following:
     sentences.
 
  2. A short, self-contained code snippet to reproduce the bug, ideally allowing
-    a simple copy and paste to reproduce. Please do your best to reduce the code 
+    a simple copy and paste to reproduce. Please do your best to reduce the code
     snippet to the minimum required.
 
  3. The actual outcome of the code snippet
@@ -42,7 +42,7 @@ If you are reporting a bug, please do your best to include the following:
 
 We have preloaded the issue creation page with a Markdown template that you can
 use to organize this information.
-        
+
 Thank you for your help in keeping bug reports complete, targeted and descriptive.
 
 Retrieving and installing the latest version of the code
@@ -79,8 +79,8 @@ You can check out the latest sources with the command (see
 
     git clone https://github.com:matplotlib/matplotlib.git
 
-and navigate to the :file:`matplotlib` directory. If you have the proper privileges, 
-you can use ``git@`` instead of  ``https://``, which works through the ssh protocol 
+and navigate to the :file:`matplotlib` directory. If you have the proper privileges,
+you can use ``git@`` instead of  ``https://``, which works through the ssh protocol
 and might be easier to use if you are using 2-factor authentication.
 
 
@@ -427,7 +427,7 @@ Developing a new backend
 ------------------------
 
 If you are working on a custom backend, the *backend* setting in
-:file:`matplotlibrc` (:ref:`sphx_glr_tutorials_01_introductory_customizing.py`) supports an
+:file:`matplotlibrc` (:ref:`sphx_glr_tutorials_introductory_customizing.py`) supports an
 external backend via the ``module`` directive.  If
 :file:`my_backend.py` is a Matplotlib backend in your
 :envvar:`PYTHONPATH`, you can set it on one of several ways

diff --git a/doc/faq/howto_faq.rst b/doc/faq/howto_faq.rst
@@ -48,7 +48,7 @@ If you only want to use the `pandas` converter for `datetime64` values ::
 Find all objects in a figure of a certain type
 ----------------------------------------------
 
-Every Matplotlib artist (see :ref:`sphx_glr_tutorials_02_intermediate_artists.py`) has a method
+Every Matplotlib artist (see :ref:`sphx_glr_tutorials_intermediate_artists.py`) has a method
 called :meth:`~matplotlib.artist.Artist.findobj` that can be used to
 recursively search the artist for any artists it may contain that meet
 some criteria (e.g., match all :class:`~matplotlib.lines.Line2D`
@@ -160,7 +160,7 @@ labels::
     ax = fig.add_subplot(111)
 
 You can control the defaults for these parameters in your
-:file:`matplotlibrc` file; see :ref:`sphx_glr_tutorials_01_introductory_customizing.py`.  For
+:file:`matplotlibrc` file; see :ref:`sphx_glr_tutorials_introductory_customizing.py`.  For
 example, to make the above setting permanent, you would set::
 
     figure.subplot.bottom : 0.2   # the bottom of the subplots of the figure
@@ -201,7 +201,7 @@ Automatically make room for tick labels
 .. note::
    This is now easier to handle than ever before.
    Calling :func:`~matplotlib.pyplot.tight_layout` can fix many common
-   layout issues. See the :ref:`sphx_glr_tutorials_02_intermediate_tight_layout_guide.py`.
+   layout issues. See the :ref:`sphx_glr_tutorials_intermediate_tight_layout_guide.py`.
 
    The information below is kept here in case it is useful for other
    purposes.

diff --git a/doc/faq/installing_faq.rst b/doc/faq/installing_faq.rst
@@ -34,7 +34,7 @@ and run it with::
 
 This will give you additional information about which backends matplotlib is
 loading, version information, and more. At this point you might want to make
-sure you understand matplotlib's :ref:`configuration <sphx_glr_tutorials_01_introductory_customizing.py>`
+sure you understand matplotlib's :ref:`configuration <sphx_glr_tutorials_introductory_customizing.py>`
 process, governed by the :file:`matplotlibrc` configuration file which contains
 instructions within and the concept of the matplotlib backend.
 

diff --git a/doc/faq/troubleshooting_faq.rst b/doc/faq/troubleshooting_faq.rst
@@ -108,7 +108,7 @@ please provide the following information in your e-mail to the
 
 
   * any customizations to your ``matplotlibrc`` file (see
-    :ref:`sphx_glr_tutorials_01_introductory_customizing.py`).
+    :ref:`sphx_glr_tutorials_introductory_customizing.py`).
 
   * if the problem is reproducible, please try to provide a *minimal*,
     standalone Python script that demonstrates the problem.  This is

diff --git a/doc/users/intro.rst b/doc/users/intro.rst
@@ -62,10 +62,10 @@ The Matplotlib code is conceptually divided into three parts: the
 *pylab interface* is the set of functions provided by
 :mod:`matplotlib.pylab` which allow the user to create plots with code
 quite similar to MATLAB figure generating code
-(:ref:`sphx_glr_tutorials_01_introductory_pyplot.py`).  The *Matplotlib frontend* or *Matplotlib
+(:ref:`sphx_glr_tutorials_introductory_pyplot.py`).  The *Matplotlib frontend* or *Matplotlib
 API* is the set of classes that do the heavy lifting, creating and
 managing figures, text, lines, plots and so on
-(:ref:`sphx_glr_tutorials_02_intermediate_artists.py`).  This is an abstract interface that knows
+(:ref:`sphx_glr_tutorials_intermediate_artists.py`).  This is an abstract interface that knows
 nothing about output.  The *backends* are device-dependent drawing
 devices, aka renderers, that transform the frontend representation to
 hardcopy or a display device (:ref:`what-is-a-backend`).  Example

diff --git a/doc/users/prev_whats_new/whats_new_0.99.rst b/doc/users/prev_whats_new/whats_new_0.99.rst
@@ -11,11 +11,11 @@ New in matplotlib 0.99
 New documentation
 -----------------
 
-Jae-Joon Lee has written two new guides :ref:`sphx_glr_tutorials_02_intermediate_legend_guide.py`
+Jae-Joon Lee has written two new guides :ref:`sphx_glr_tutorials_intermediate_legend_guide.py`
 and :ref:`plotting-guide-annotation`.  Michael Sarahan has written
-:ref:`sphx_glr_tutorials_01_introductory_images.py`.  John Hunter has written two new tutorials on
-working with paths and transformations: :ref:`sphx_glr_tutorials_03_advanced_path_tutorial.py` and
-:ref:`sphx_glr_tutorials_03_advanced_transforms_tutorial.py`.
+:ref:`sphx_glr_tutorials_introductory_images.py`.  John Hunter has written two new tutorials on
+working with paths and transformations: :ref:`sphx_glr_tutorials_advanced_path_tutorial.py` and
+:ref:`sphx_glr_tutorials_advanced_transforms_tutorial.py`.
 
 .. _whats-new-mplot3d:
 

diff --git a/doc/users/prev_whats_new/whats_new_1.0.rst b/doc/users/prev_whats_new/whats_new_1.0.rst
@@ -23,7 +23,7 @@ Sophisticated subplot grid layout
 
 Jae-Joon Lee has written :mod:`~matplotlib.gridspec`, a new module for
 doing complex subplot layouts, featuring row and column spans and
-more.  See :ref:`sphx_glr_tutorials_02_intermediate_gridspec.py` for a tutorial overview.
+more.  See :ref:`sphx_glr_tutorials_intermediate_gridspec.py` for a tutorial overview.
 
 .. figure:: ../../gallery/userdemo/images/sphx_glr_demo_gridspec01_000.png
    :target: ../../gallery/userdemo/demo_gridspec01.html

diff --git a/doc/users/prev_whats_new/whats_new_1.1.rst b/doc/users/prev_whats_new/whats_new_1.1.rst
@@ -87,7 +87,7 @@ The usage of this functionality can be as simple as ::
 
 and it will adjust the spacing between subplots
 so that the axis labels do not overlap with neighboring subplots. A
-:ref:`sphx_glr_tutorials_02_intermediate_tight_layout_guide.py` has been created to show how to use
+:ref:`sphx_glr_tutorials_intermediate_tight_layout_guide.py` has been created to show how to use
 this new tool.
 
 PyQT4, PySide, and IPython
@@ -116,7 +116,7 @@ legends for complex plots such as :meth:`~matplotlib.pyplot.stem` plots
 will now display correctly. Second, the 'best' placement of a legend has
 been improved in the presence of NANs.
 
-See the :ref:`sphx_glr_tutorials_02_intermediate_legend_guide.py` for more detailed explanation and
+See the :ref:`sphx_glr_tutorials_intermediate_legend_guide.py` for more detailed explanation and
 examples.
 
 .. figure:: ../../gallery/text_labels_and_annotations/images/sphx_glr_legend_demo_004.png
@@ -228,7 +228,3 @@ Other improvements
   other colormaps :ref:`here <color-colormaps_reference>`.
 
 * Many bug fixes and documentation improvements.
-
-
-
-
diff --git a/doc/users/prev_whats_new/whats_new_1.4.rst b/doc/users/prev_whats_new/whats_new_1.4.rst
@@ -410,7 +410,7 @@ instead of ``:context:`` any time you want to reset the context.
 
 Legend and PathEffects documentation
 ------------------------------------
-The :ref:`sphx_glr_tutorials_02_intermediate_legend_guide.py` and :ref:`sphx_glr_tutorials_03_advanced_patheffects_guide.py` have both been
+The :ref:`sphx_glr_tutorials_intermediate_legend_guide.py` and :ref:`sphx_glr_tutorials_advanced_patheffects_guide.py` have both been
 updated to better reflect the full potential of each of these powerful
 features.
 
@@ -427,5 +427,3 @@ rectangle stay on the axes after you release the mouse.
 GAE integration
 ---------------
 Matplotlib will now run on google app engine.
-
-
diff --git a/doc/users/shell.rst b/doc/users/shell.rst
@@ -92,7 +92,7 @@ are going to need to understand what a matplotlib backend is
 With the TkAgg backend, which uses the Tkinter user interface toolkit,
 you can use matplotlib from an arbitrary non-gui python shell.  Just set your
 ``backend : TkAgg`` and ``interactive : True`` in your
-:file:`matplotlibrc` file (see :ref:`sphx_glr_tutorials_01_introductory_customizing.py`) and fire
+:file:`matplotlibrc` file (see :ref:`sphx_glr_tutorials_introductory_customizing.py`) and fire
 up python.  Then::
 
   >>> from pylab import *

diff --git a/examples/recipes/placing_text_boxes.py b/examples/recipes/placing_text_boxes.py
@@ -3,7 +3,7 @@
 ==================
 
 When decorating axes with text boxes, two useful tricks are to place
-the text in axes coordinates (see :ref:`sphx_glr_tutorials_03_advanced_transforms_tutorial.py`), so the
+the text in axes coordinates (see :ref:`sphx_glr_tutorials_advanced_transforms_tutorial.py`), so the
 text doesn't move around with changes in x or y limits.  You can also
 use the ``bbox`` property of text to surround the text with a
 :class:`~matplotlib.patches.Patch` instance -- the ``bbox`` keyword

diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -502,7 +502,7 @@ def legend(self, *args, **kwargs):
         -----
 
         Not all kinds of artist are supported by the legend command. See
-        :ref:`sphx_glr_tutorials_02_intermediate_legend_guide.py` for details.
+        :ref:`sphx_glr_tutorials_intermediate_legend_guide.py` for details.
 
         Examples
         --------

diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -1450,7 +1450,7 @@ def legend(self, *args, **kwargs):
         Notes
         -----
         Not all kinds of artist are supported by the legend command. See
-        :ref:`sphx_glr_tutorials_02_intermediate_legend_guide.py` for details.
+        :ref:`sphx_glr_tutorials_intermediate_legend_guide.py` for details.
         """
 
         # If no arguments given, collect up all the artists on the figure

diff --git a/lib/matplotlib/legend.py b/lib/matplotlib/legend.py
@@ -8,7 +8,7 @@
     Most users would normally create a legend via the
     :meth:`~matplotlib.axes.Axes.legend` function. For more details on legends
     there is also a :ref:`legend guide
-    <sphx_glr_tutorials_02_intermediate_legend_guide.py>`.
+    <sphx_glr_tutorials_intermediate_legend_guide.py>`.
 
 The Legend class can be considered as a container of legend handles
 and legend texts. Creation of corresponding legend handles from the
@@ -19,7 +19,7 @@
 Note that not all kinds of artist are supported by the legend yet by default
 but it is possible to extend the legend handler's capabilities to support
 arbitrary objects. See the :ref:`legend guide
-<sphx_glr_tutorials_02_intermediate_legend_guide.py>` for more information.
+<sphx_glr_tutorials_intermediate_legend_guide.py>` for more information.
 
 """
 from __future__ import (absolute_import, division, print_function,

diff --git a/lib/matplotlib/legend_handler.py b/lib/matplotlib/legend_handler.py
@@ -2,7 +2,7 @@
 This module defines default legend handlers.
 
 It is strongly encouraged to have read the :ref:`legend guide
-<sphx_glr_tutorials_02_intermediate_legend_guide.py>` before this documentation.
+<sphx_glr_tutorials_intermediate_legend_guide.py>` before this documentation.
 
 Legend handlers are expected to be a callable object with a following
 signature. ::

diff --git a/tutorials/03_advanced/README.txt → tutorials/advanced/README.txt b/tutorials/03_advanced/README.txt → tutorials/advanced/README.txt
diff --git a/tutorials/03_advanced/path_tutorial.py → tutorials/advanced/path_tutorial.py b/tutorials/03_advanced/path_tutorial.py → tutorials/advanced/path_tutorial.py
diff --git a/tutorials/03_advanced/patheffects_guide.py → tutorials/advanced/patheffects_guide.py b/tutorials/03_advanced/patheffects_guide.py → tutorials/advanced/patheffects_guide.py
diff --git a/tutorials/03_advanced/transforms_tutorial.py → tutorials/advanced/transforms_tutorial.py b/tutorials/03_advanced/transforms_tutorial.py → tutorials/advanced/transforms_tutorial.py
diff --git a/tutorials/02_intermediate/README.txt → tutorials/intermediate/README.txt b/tutorials/02_intermediate/README.txt → tutorials/intermediate/README.txt
diff --git a/tutorials/02_intermediate/artists.py → tutorials/intermediate/artists.py b/tutorials/02_intermediate/artists.py → tutorials/intermediate/artists.py
diff --git a/tutorials/02_intermediate/gridspec.py → tutorials/intermediate/gridspec.py b/tutorials/02_intermediate/gridspec.py → tutorials/intermediate/gridspec.py
diff --git a/tutorials/02_intermediate/legend_guide.py → tutorials/intermediate/legend_guide.py b/tutorials/02_intermediate/legend_guide.py → tutorials/intermediate/legend_guide.py
diff --git a/...als/02_intermediate/tight_layout_guide.py → tutorials/intermediate/tight_layout_guide.py b/...als/02_intermediate/tight_layout_guide.py → tutorials/intermediate/tight_layout_guide.py
@@ -108,7 +108,7 @@ def example_plot(ax, fontsize=12):
 ###############################################################################
 # It works with subplots created with
 # :func:`~matplotlib.pyplot.subplot2grid`. In general, subplots created
-# from the gridspec (:ref:`sphx_glr_tutorials_02_intermediate_gridspec.py`) will work.
+# from the gridspec (:ref:`sphx_glr_tutorials_intermediate_gridspec.py`) will work.
 
 plt.close('all')
 fig = plt.figure()

diff --git a/tutorials/01_introductory/README.txt → tutorials/introductory/README.txt b/tutorials/01_introductory/README.txt → tutorials/introductory/README.txt
diff --git a/tutorials/01_introductory/customizing.py → tutorials/introductory/customizing.py b/tutorials/01_introductory/customizing.py → tutorials/introductory/customizing.py
diff --git a/tutorials/01_introductory/images.py → tutorials/introductory/images.py b/tutorials/01_introductory/images.py → tutorials/introductory/images.py
diff --git a/tutorials/01_introductory/lifecycle.py → tutorials/introductory/lifecycle.py b/tutorials/01_introductory/lifecycle.py → tutorials/introductory/lifecycle.py
@@ -26,7 +26,7 @@
 The second is based on MATLAB and uses
 a state-based interface. This is encapsulated in the :mod:`pyplot`
 module. See the :ref:`pyplot tutorials
-<sphx_glr_tutorials_01_introductory_pyplot.py>`
+<sphx_glr_tutorials_introductory_pyplot.py>`
 for a more in-depth look at the pyplot interface.
 
 Most of the terms are straightforward but the main thing to remember
@@ -86,7 +86,7 @@
 #
 #    Figures can have multiple axes on them. For information on how to do this,
 #    see the :ref:`Tight Layout tutorial
-#    <sphx_glr_tutorials_02_intermediate_tight_layout_guide.py>`.
+#    <sphx_glr_tutorials_intermediate_tight_layout_guide.py>`.
 
 fig, ax = plt.subplots()
 
@@ -149,7 +149,7 @@
 # that we create. To do this we'll set the ``autolayout`` value of our
 # rcParams. For more information on controlling the style, layout, and
 # other features of plots with rcParams, see
-# :ref:`sphx_glr_tutorials_01_introductory_customizing.py`.
+# :ref:`sphx_glr_tutorials_introductory_customizing.py`.
 
 plt.rcParams.update({'figure.autolayout': True})
 

diff --git a/tutorials/01_introductory/pyplot.py → tutorials/introductory/pyplot.py b/tutorials/01_introductory/pyplot.py → tutorials/introductory/pyplot.py
@@ -307,7 +307,7 @@ def f(t):
 # it annoying that states (specifically the current image, figure and axes)
 # are being maintained for you behind the scenes, don't despair: this is just a thin
 # stateful wrapper around an object oriented API, which you can use
-# instead (see :ref:`sphx_glr_tutorials_02_intermediate_artists.py`)
+# instead (see :ref:`sphx_glr_tutorials_intermediate_artists.py`)
 #
 # If you are making lots of figures, you need to be aware of one
 # more thing: the memory required for a figure is not completely

diff --git a/tutorials/01_introductory/sample_plots.py → tutorials/introductory/sample_plots.py b/tutorials/01_introductory/sample_plots.py → tutorials/introductory/sample_plots.py