Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit c098519

Browse files
timhoffmtimhoffm
authored
Merge pull request #11257 from ImportanceOfBeingErnest/sort-gallery-alternative
DOC: Sort gallery subsections by explicit list then by filename
2 parents c93957b + 641eb38 commit c098519

4 files changed

Lines changed: 118 additions & 28 deletions

File tree

‎doc-requirements.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,4 +12,4 @@ ipython
1212
ipywidgets
1313
numpydoc>=0.4
1414
pillow
15-
sphinx-gallery>=0.1.12
15+
sphinx-gallery>=0.1.13

‎doc/conf.py‎

Lines changed: 7 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,6 @@
99
# All configuration values have a default value; values that are commented out
1010
# serve to show the default value.
1111

12-
from glob import glob
1312
import os
1413
import shutil
1514
import sys
@@ -72,8 +71,10 @@ def _check_deps():
7271
_check_deps()
7372

7473
# Import only after checking for dependencies.
75-
from sphinx_gallery.sorting import ExplicitOrder
76-
# This is only necessary to monkey patch the signature later on.
74+
# gallery_order.py from the sphinxext folder provides the classes that
75+
# allow custom ordering of sections and subsections of the gallery
76+
import sphinxext.gallery_order as gallery_order
77+
# The following import is only necessary to monkey patch the signature later on
7778
from sphinx_gallery import gen_rst
7879

7980
if shutil.which('dot') is None:
@@ -94,27 +95,7 @@ def _check_deps():
9495
'cycler': ('https://matplotlib.org/cycler', None),
9596
}
9697

97-
explicit_order_folders = [
98-
'../examples/api',
99-
'../examples/pyplots',
100-
'../examples/subplots_axes_and_figures',
101-
'../examples/color',
102-
'../examples/statistics',
103-
'../examples/lines_bars_and_markers',
104-
'../examples/images_contours_and_fields',
105-
'../examples/shapes_and_collections',
106-
'../examples/text_labels_and_annotations',
107-
'../examples/pie_and_polar_charts',
108-
'../examples/style_sheets',
109-
'../examples/axes_grid',
110-
'../examples/showcase',
111-
'../tutorials/introductory',
112-
'../tutorials/intermediate',
113-
'../tutorials/advanced']
114-
for folder in sorted(glob('../examples/*') + glob('../tutorials/*')):
115-
if not os.path.isdir(folder) or folder in explicit_order_folders:
116-
continue
117-
explicit_order_folders.append(folder)
98+
11899

119100
# Sphinx gallery configuration
120101
sphinx_gallery_conf = {
@@ -128,7 +109,8 @@ def _check_deps():
128109
'scipy': 'https://docs.scipy.org/doc/scipy/reference',
129110
},
130111
'backreferences_dir': 'api/_as_gen',
131-
'subsection_order': ExplicitOrder(explicit_order_folders),
112+
'subsection_order': gallery_order.sectionorder,
113+
'within_subsection_order': gallery_order.subsectionorder,
132114
'min_reported_time': 1,
133115
}
134116

‎doc/devel/documenting_mpl.rst‎

Lines changed: 24 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -42,12 +42,12 @@ using the Sphinx_ documentation generation tool. There are several extra
4242
requirements that are needed to build the documentation. They are listed in
4343
:file:`doc-requirements.txt` and listed below:
4444

45-
* Sphinx>=1.3, !=1.5.0, !=1.6.4
45+
* Sphinx>=1.3, !=1.5.0, !=1.6.4, !=1.7.3
4646
* colorspacious
4747
* IPython
4848
* numpydoc>=0.4
4949
* Pillow
50-
* sphinx-gallery>=0.1.12
50+
* sphinx-gallery>=0.1.13
5151
* graphviz
5252

5353
.. note::
@@ -680,6 +680,28 @@ are delimited by a line of `###` characters:
680680
681681
In this way text, code, and figures are output in a "notebook" style.
682682

683+
Order of examples in the gallery
684+
--------------------------------
685+
686+
The order of the sections of the :ref:`tutorials` and the :ref:`gallery`, as
687+
well as the order of the examples within each section are determined in a
688+
two step process from within the :file:`/doc/sphinxext/gallery_order.py`:
689+
690+
* *Explicit order*: This file contains a list of folders for the section order
691+
and a list of examples for the subsection order. The order of the items
692+
shown in the doc pages is the order those items appear in those lists.
693+
* *Implicit order*: If a folder or example is not in those lists, it will be
694+
appended after the explicitely ordered items and all of those additional
695+
items will be ordered by pathname (for the sections) or by filename
696+
(for the subsections).
697+
698+
As a consequence, if you want to let your example appear in a certain
699+
position in the gallery, extend those lists with your example.
700+
In case no explicit order is desired or necessary, still make sure
701+
to name your example consistently, i.e. use the main function or subject
702+
of the example as first word in the filename; e.g. an image example
703+
should ideally be named similar to :file:`imshow_mynewexample.py`.
704+
683705
Miscellaneous
684706
=============
685707

‎doc/sphinxext/gallery_order.py‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
"""
2+
Configuration for the order of gallery sections and examples.
3+
Paths are relative to the conf.py file.
4+
5+
"""
6+
7+
from sphinx_gallery.sorting import ExplicitOrder
8+
9+
# Gallery sections shall be diplayed in the following order.
10+
# Non-matching sections are appended.
11+
explicit_order_folders = [
12+
'../examples/api',
13+
'../examples/pyplots',
14+
'../examples/subplots_axes_and_figures',
15+
'../examples/color',
16+
'../examples/statistics',
17+
'../examples/lines_bars_and_markers',
18+
'../examples/images_contours_and_fields',
19+
'../examples/shapes_and_collections',
20+
'../examples/text_labels_and_annotations',
21+
'../examples/pie_and_polar_charts',
22+
'../examples/style_sheets',
23+
'../examples/axes_grid1',
24+
'../examples/axisartist',
25+
'../examples/showcase',
26+
'../tutorials/introductory',
27+
'../tutorials/intermediate',
28+
'../tutorials/advanced']
29+
30+
31+
class MplExplicitOrder(ExplicitOrder):
32+
""" for use within the 'subsection_order' key"""
33+
def __call__(self, item):
34+
"""Return a string determining the sort order."""
35+
if item in self.ordered_list:
36+
return "{:04d}".format(self.ordered_list.index(item))
37+
else:
38+
# ensure not explicitly listed items come last.
39+
return "zzz" + item
40+
41+
42+
# Subsection order:
43+
# Subsections are ordered by filename, unless they appear in the following
44+
# lists in which case the list order determines the order within the section.
45+
# Examples/tutorials that do not appear in a list will be appended.
46+
47+
list_all = [
48+
# **Tutorials**
49+
# introductory
50+
"usage", "pyplot", "sample_plots", "images", "lifecycle", "customizing",
51+
# intermediate
52+
"artists", "legend_guide", "color_cycle", "gridspec",
53+
"constrainedlayout_guide", "tight_layout_guide",
54+
# advanced
55+
# text
56+
"text_intro", "text_props",
57+
# colors
58+
"colors",
59+
60+
# **Examples**
61+
# color
62+
"color_demo",
63+
# pies
64+
"pie_features", "pie_demo2",
65+
]
66+
explicit_subsection_order = [item + ".py" for item in list_all]
67+
68+
69+
class MplExplicitSubOrder(object):
70+
""" for use within the 'within_subsection_order' key """
71+
def __init__(self, src_dir):
72+
self.src_dir = src_dir #src_dir is unused here
73+
self.ordered_list = explicit_subsection_order
74+
75+
def __call__(self, item):
76+
"""Return a string determining the sort order."""
77+
if item in self.ordered_list:
78+
return "{:04d}".format(self.ordered_list.index(item))
79+
else:
80+
# ensure not explicitly listed items come last.
81+
return "zzz" + item
82+
83+
84+
# Provide the above classes for use in conf.py
85+
sectionorder = MplExplicitOrder(explicit_order_folders)
86+
subsectionorder = MplExplicitSubOrder

0 commit comments

Comments
 (0)