Sort gallery subsections by explicit list then by filename

ImportanceOfBeingErnest · ImportanceOfBeingErnest · commit 6b8c6413c894 · 2018-05-15T23:30:17.000+02:00
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,7 +71,7 @@ def _check_deps():
 _check_deps()
 
 # Import only after checking for dependencies.
-from sphinx_gallery.sorting import ExplicitOrder
+import sphinxext.gallery_order as gallery_order
 # This is only necessary to monkey patch the signature later on.
 from sphinx_gallery import gen_rst
 
@@ -94,27 +93,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 +107,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::
diff --git a/doc/sphinxext/gallery_order.py b/doc/sphinxext/gallery_order.py
@@ -0,0 +1,82 @@
+"""
+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):
+        if item in self.ordered_list:
+            return "{:04d}".format(self.ordered_list.index(item))
+        else:
+            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.
+
+# Tutorials:
+list_introductory = ["usage", "pyplot", "sample_plots", "images", "lifecycle",
+                     "customizing"]
+list_intermediate = ["artists", "legend_guide", "color_cycle", "gridspec",
+                     "constrainedlayout_guide", "tight_layout_guide"]
+list_advanced = []
+list_text = ["text_intro", "text_props"]
+list_colors = ["colors"]
+
+list_tutorials = list_introductory + list_intermediate + list_advanced + \
+                 list_text + list_colors
+
+# Examples:
+list_color = ["color_demo"]
+list_pies = ["pie_features", "pie_demo2"]
+list_examples = list_color + list_pies
+
+# All items:
+list_all = list_tutorials + list_examples
+list_all = [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 = list_all
+
+    def __call__(self, item):
+        if item in self.ordered_list:
+            return "{:04d}".format(self.ordered_list.index(item))
+        else:
+            return "zzz" + item
+
+
+# Provide the above classes for use in conf.py
+sectionorder = MplExplicitOrder(explicit_order_folders)
+subsectionorder = MplExplicitSubOrder
