Skip to content

Fix #25032 by reading gallery ordering from a txt file in galleries folder #27991

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Fix #25032 by reading gallery ordering from a txt file in galleries folder #27991

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
eb8c12a
Fix #25032 for plot_types
NirobNabil Mar 29, 2024
509c5bf
Add gallery_order.txt files for plot_types
NirobNabil Mar 29, 2024
3c031db
Fix bug: plot_types subdirectory ordering logic was faulty
NirobNabil Mar 29, 2024
8201f0e
Add gallery_order.txt files for examples folder and tidy up gallery_…
NirobNabil Mar 29, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
112 changes: 45 additions & 67 deletions doc/sphinxext/gallery_order.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,49 +4,46 @@
"""

from sphinx_gallery.sorting import ExplicitOrder
import os


# Utility functions
def get_ordering(dir, include_directory_path=False):
"""Read gallery_order.txt in dir and return content of the file as a List"""
file_path = os.path.join(dir, 'gallery_order.txt')
f = open(file_path, "r")
lines = [line.replace('\n', '') for line in f.readlines()]
ordered_list = []
for line in lines:
if line == "unsorted":
ordered_list.append(UNSORTED)
else:
if include_directory_path:
ordered_list.append(os.path.join(dir, line))
else:
ordered_list.append(line)

Comment on lines +13 to +25
Copy link
Member

@story645 story645 May 9, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
file_path = os.path.join(dir, 'gallery_order.txt')
f = open(file_path, "r")
lines = [line.replace('\n', '') for line in f.readlines()]
ordered_list = []
for line in lines:
if line == "unsorted":
ordered_list.append(UNSORTED)
else:
if include_directory_path:
ordered_list.append(os.path.join(dir, line))
else:
ordered_list.append(line)
ordered_list = []
with open(os.path.join(dir, 'gallery_order.txt'), 'r') as f:
for line in f.readlines():
line = line.rstrip("\n")
if line == "unsorted":
ordered_list.append(UNSORTED)
elif include_directory_path:
ordered_list.append(os.path.join(dir, line))
else:
ordered_list.append(line)

um this is mostly stylistic, but it does remove one loop and I think you should be able to use context managers here

return ordered_list


def list_directory(parent_dir):
"""Return list of sub directories at a directory"""
root, dirs, files = next(os.walk(parent_dir))
return [os.path.join(root, dir) for dir in dirs]

# Gallery sections shall be displayed in the following order.
# Non-matching sections are inserted at the unsorted position

UNSORTED = "unsorted"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should maybe be moved to top of file if it's being used in the listing function above (or passed in as a variable)


examples_order = [
'../galleries/examples/lines_bars_and_markers',
'../galleries/examples/images_contours_and_fields',
'../galleries/examples/subplots_axes_and_figures',
'../galleries/examples/statistics',
'../galleries/examples/pie_and_polar_charts',
'../galleries/examples/text_labels_and_annotations',
'../galleries/examples/color',
'../galleries/examples/shapes_and_collections',
'../galleries/examples/style_sheets',
'../galleries/examples/pyplots',
'../galleries/examples/axes_grid1',
'../galleries/examples/axisartist',
'../galleries/examples/showcase',
UNSORTED,
'../galleries/examples/userdemo',
]

tutorials_order = [
'../galleries/tutorials/introductory',
'../galleries/tutorials/intermediate',
'../galleries/tutorials/advanced',
UNSORTED,
'../galleries/tutorials/provisional'
]
plot_types_directory = "../galleries/plot_types/"
plot_types_order = get_ordering(plot_types_directory, include_directory_path=True)
Comment on lines +40 to +41
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

does this solution generalize? (to the other folders?) I like that it looks relatively lightweight

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes it does, because other folders are also structured in the same way as plot_types directory. Except for the users_explain directory, because its not included in explicit_order_folders but some of it's files are in list_all. I'm not sure why users_explain directory is not included in explicit_order_folders but because of this, i think its currently being sorted according to default values but that doesn't seem to totally line up with my understanding. because the sort keys returned by MplExplicitOrder will be UNSORTED thus defaulting to alphabetic ordering or LOC based ordering. But that doesn't seem to be the case when i'm going through the user guide section in doc website. Any clarification on how user_explain is sorted will help me greatly.

Other than that, rest of the folders will work fine with my current implementation as far as i understand. I'll push an update soon with the modifications for other other folders.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry for not explaining this earlier, user_explain doesn't have a gallery landing page, instead it uses https://github.com/matplotlib/matplotlib/blob/main/doc/users/index.rst


plot_types_order = [
'../galleries/plot_types/basic',
'../galleries/plot_types/stats',
'../galleries/plot_types/arrays',
'../galleries/plot_types/unstructured',
'../galleries/plot_types/3D',
UNSORTED
]

folder_lists = [examples_order, tutorials_order, plot_types_order]
examples_directory = "../galleries/examples/"
examples_order = get_ordering(examples_directory, include_directory_path=True)

folder_lists = [examples_order, plot_types_order]
explicit_order_folders = [fd for folders in folder_lists
for fd in folders[:folders.index(UNSORTED)]]
explicit_order_folders.append(UNSORTED)
Expand All @@ -69,39 +66,20 @@
# Examples/tutorials that do not appear in a list will be appended.

list_all = [
# **Tutorials**
# introductory
"quick_start", "pyplot", "images", "lifecycle", "customizing",
# intermediate
"artists", "legend_guide", "color_cycle",
"constrainedlayout_guide", "tight_layout_guide",
# advanced
# text
"text_intro", "text_props",
# colors
"colors",

# **Examples**
# color
"color_demo",
# pies
"pie_features", "pie_demo2",

# **Plot Types
# Basic
"plot", "scatter_plot", "bar", "stem", "step", "fill_between",
# Arrays
"imshow", "pcolormesh", "contour", "contourf",
"barbs", "quiver", "streamplot",
# Stats
"hist_plot", "boxplot_plot", "errorbar_plot", "violin",
"eventplot", "hist2d", "hexbin", "pie",
# Unstructured
"tricontour", "tricontourf", "tripcolor", "triplot",
# Spines
"spines", "spine_placement_demo", "spines_dropped",
"multiple_yaxis_with_spines", "centered_spines_with_arrows",
]
# folders that don't contain gallery_order.txt file can

Check failure on line 69 in doc/sphinxext/gallery_order.py

View workflow job for this annotation

GitHub Actions / flake8 

[flake8] reported by reviewdog 🐶
W291 trailing whitespace

Raw Output:
./doc/sphinxext/gallery_order.py:69:60: W291 trailing whitespace
# list their file orderings here

Check failure on line 70 in doc/sphinxext/gallery_order.py

View workflow job for this annotation

GitHub Actions / flake8 

[flake8] reported by reviewdog 🐶
W291 trailing whitespace

Raw Output:
./doc/sphinxext/gallery_order.py:70:37: W291 trailing whitespace
]


for dir in list_directory(plot_types_directory):
try:
ordered_subdirs = get_ordering(dir, include_directory_path=False)
list_all.extend(ordered_subdirs)
except FileNotFoundError:
# Fallback to ordering already defined in list_all
pass
Comment on lines +78 to +80
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can this be logged to sphinx just in case this ignores something that shouldn't be ignored?



explicit_subsection_order = [item + ".py" for item in list_all]


Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/color/gallery_order.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
color_demo
unsorted
15 changes: 15 additions & 0 deletions galleries/examples/gallery_order.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
lines_bars_and_markers
images_contours_and_fields
subplots_axes_and_figures
statistics
pie_and_polar_charts
text_labels_and_annotations
color
shapes_and_collections
style_sheets
pyplots
axes_grid1
axisartist
showcase
unsorted
userdemo
2 changes: 2 additions & 0 deletions galleries/examples/pie_and_polar_charts/gallery_order.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
pie_features
unsorted
5 changes: 5 additions & 0 deletions galleries/examples/spines/gallery_order.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
spines
spine_placement_demo
spines_dropped
multiple_yaxis_with_spines
centered_spines_with_arrows
6 changes: 6 additions & 0 deletions galleries/plot_types/arrays/gallery_order.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
imshow
pcolormesh
contourcontourf
barbs
quiver
streamplot
6 changes: 6 additions & 0 deletions galleries/plot_types/basic/gallery_order.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
plot
scatter_plot
bar
stem
step
fill_between
6 changes: 6 additions & 0 deletions galleries/plot_types/gallery_order.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
basic
stats
arrays
unstructured
3D
unsorted
8 changes: 8 additions & 0 deletions galleries/plot_types/stats/gallery_order.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
hist_plot
boxplot_plot
errorbar_plot
violin
eventplot
hist2d
hexbin
pie
4 changes: 4 additions & 0 deletions galleries/plot_types/unstructured/gallery_order.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
tricontour
tricontourf
tripcolor
triplot
Loading