adding gallery sorting

Author: choldgraf

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

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,18 @@ def _check_deps():
   'pandas': ('http://pandas.pydata.org/pandas-docs/stable', None)
   }
 
+explicit_order_folders = ['../examples/pyplots',
+                          '../examples/statistics',
+                          '../examples/color',
+                          '../examples/pylab_examples',
+                          '../examples/showcase',
+                          '../tutorials/introductory',
+                          '../tutorials/intermediate',
+                          '../tutorials/advanced']
+for folder in 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 +121,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

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

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.

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.
 

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

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

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
         --------

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