matplotlib · timhoffm · May 16, 2018 · May 15, 2018
diff --git a/doc-requirements.txt b/doc-requirements.txt
@@ -12,4 +12,4 @@ ipython
 ipywidgets
 numpydoc>=0.4
 pillow
-sphinx-gallery>=0.1.12
+sphinx-gallery>=0.1.13
diff --git a/doc/conf.py b/doc/conf.py
@@ -9,7 +9,6 @@
 # All configuration values have a default value; values that are commented out
 # serve to show the default value.
 
-from glob import glob
 import os
 import shutil
 import sys
@@ -72,8 +71,10 @@ def _check_deps():
 _check_deps()
 
 # Import only after checking for dependencies.
-from sphinx_gallery.sorting import ExplicitOrder
-# This is only necessary to monkey patch the signature later on.
+# gallery_order.py from the sphinxext folder provides the classes that
+# allow custom ordering of sections and subsections of the gallery
+import sphinxext.gallery_order as gallery_order
+# The following import is only necessary to monkey patch the signature later on
 from sphinx_gallery import gen_rst
 
 if shutil.which('dot') is None:
@@ -94,27 +95,7 @@ def _check_deps():
     'cycler': ('https://matplotlib.org/cycler', 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 = {
@@ -128,7 +109,8 @@ def _check_deps():
         'scipy': 'https://docs.scipy.org/doc/scipy/reference',
     },
     'backreferences_dir': 'api/_as_gen',
-    'subsection_order': ExplicitOrder(explicit_order_folders),
+    'subsection_order': gallery_order.sectionorder,
+    'within_subsection_order': gallery_order.subsectionorder,
     'min_reported_time': 1,
 }
 

diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
@@ -42,12 +42,12 @@ using the Sphinx_ documentation generation tool. There are several extra
 requirements that are needed to build the documentation. They are listed in
 :file:`doc-requirements.txt` and listed below:
 
-* Sphinx>=1.3, !=1.5.0, !=1.6.4
+* Sphinx>=1.3, !=1.5.0, !=1.6.4, !=1.7.3
 * colorspacious
 * IPython
 * numpydoc>=0.4
 * Pillow
-* sphinx-gallery>=0.1.12
+* sphinx-gallery>=0.1.13
 * graphviz
 
 .. note::
@@ -680,6 +680,28 @@ are delimited by a line of `###` characters:
 
 In this way text, code, and figures are output in a "notebook" style.
 
+Order of examples in the gallery
+--------------------------------
+
+The order of the sections of the :ref:`tutorials` and the :ref:`gallery`, as
+well as the order of the examples within each section are determined in a
+two step process from within the :file:`/doc/sphinxext/gallery_order.py`:
+
+* *Explicit order*: This file contains a list of folders for the section order
+  and a list of examples for the subsection order. The order of the items
+  shown in the doc pages is the order those items appear in those lists.
+* *Implicit order*: If a folder or example is not in those lists, it will be
+  appended after the explicitely ordered items and all of those additional
+  items will be ordered by pathname (for the sections) or by filename
+  (for the subsections).
+
+As a consequence, if you want to let your example appear in a certain
+position in the gallery, extend those lists with your example.
+In case no explicit order is desired or necessary, still make sure
+to name your example consistently, i.e. use the main function or subject
+of the example as first word in the filename; e.g. an image example
+should ideally be named similar to :file:`imshow_mynewexample.py`.
+
 Miscellaneous
 =============
 

diff --git a/doc/sphinxext/gallery_order.py b/doc/sphinxext/gallery_order.py
@@ -0,0 +1,86 @@
+"""
+Configuration for the order of gallery sections and examples.
+Paths are relative to the conf.py file.
+
+"""
+
+from sphinx_gallery.sorting import ExplicitOrder
+
+# Gallery sections shall be diplayed in the following order.
+# Non-matching sections are appended.
+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_grid1',
+                          '../examples/axisartist',
+                          '../examples/showcase',
+                          '../tutorials/introductory',
+                          '../tutorials/intermediate',
+                          '../tutorials/advanced']
+
+
+class MplExplicitOrder(ExplicitOrder):
+    """ for use within the 'subsection_order' key"""
+    def __call__(self, item):
+        """Return a string determining the sort order."""
+        if item in self.ordered_list:
+            return "{:04d}".format(self.ordered_list.index(item))
+        else:
+            # ensure not explicitly listed items come last.
+            return "zzz" + item
+
+
+# Subsection order:
+# Subsections are ordered by filename, unless they appear in the following
+# lists in which case the list order determines the order within the section.
+# Examples/tutorials that do not appear in a list will be appended.
+
+list_all = [
+    #  **Tutorials**
+    #  introductory
+    "usage", "pyplot", "sample_plots", "images", "lifecycle", "customizing",
+    #  intermediate
+    "artists", "legend_guide", "color_cycle", "gridspec",
+    "constrainedlayout_guide", "tight_layout_guide",
+    #  advanced
+    #  text
+    "text_intro", "text_props",
+    #  colors
+    "colors",
+
+    #  **Examples**
+    #  color
+    "color_demo",
+    #  pies
+    "pie_features", "pie_demo2",
+    ]
+explicit_subsection_order = [item + ".py" for item in list_all]
+
+
+class MplExplicitSubOrder(object):
+    """ for use within the 'within_subsection_order' key """
+    def __init__(self, src_dir):
+        self.src_dir = src_dir #src_dir is unused here
+        self.ordered_list = explicit_subsection_order
+
+    def __call__(self, item):
+        """Return a string determining the sort order."""
+        if item in self.ordered_list:
+            return "{:04d}".format(self.ordered_list.index(item))
+        else:
+            # ensure not explicitly listed items come last.
+            return "zzz" + item
+
+
+# Provide the above classes for use in conf.py
+sectionorder = MplExplicitOrder(explicit_order_folders)
+subsectionorder = MplExplicitSubOrder