From 641eb385b41a363b6271e39cfbb926df65b63d94 Mon Sep 17 00:00:00 2001 From: ImportanceOfBeingErnest Date: Tue, 15 May 2018 23:30:17 +0200 Subject: [PATCH] Sort gallery subsections by explicit list then by filename --- doc-requirements.txt | 2 +- doc/conf.py | 32 +++---------- doc/devel/documenting_mpl.rst | 26 +++++++++- doc/sphinxext/gallery_order.py | 86 ++++++++++++++++++++++++++++++++++ 4 files changed, 118 insertions(+), 28 deletions(-) create mode 100644 doc/sphinxext/gallery_order.py diff --git a/doc-requirements.txt b/doc-requirements.txt index 8276bb1b95e1..c0ee2014cf64 100644 --- 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 index cd4045badd29..a0aa200b2764 100644 --- 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 index 794e62239bc7..3c04891ab02e 100644 --- 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 new file mode 100644 index 000000000000..06f6c207ce2d --- /dev/null +++ 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