Skip to content

DOC: Add file-based listed gallery order for examples - #31714

Merged
QuLogic merged 1 commit into
matplotlib:mainfrom
timhoffm:doc-gallery_order-txt
Jun 4, 2026
Merged

QuLogic merged 1 commit into
matplotlib:mainfrom
timhoffm:doc-gallery_order-txt

Conversation

@timhoffm

Copy link
Copy Markdown
Member

PR summary

This adds support for a file "gallery_order.txt" in gallery folders for specifying the display order or examples.

Advantages compared to the previous order approach:

  • Orders are now defined inside each gallery and not in a central list
  • The placeholder '*' allows to put some examples at the front, some at the end, and all others alphabetically sorted in the position of the placeholder
  • Checking of entries that do no exist as examples
  • Checking that all examples are listed (if no placeholder is specified)

AI Disclosure

No AI used

@github-actions github-actions Bot added Documentation: build building the docs Documentation: plot types files in galleries/plot_types Documentation: examples files in galleries/examples Documentation: tutorials files in galleries/tutorials Documentation: devdocs files in doc/devel labels May 19, 2026
@timhoffm
timhoffm force-pushed the doc-gallery_order-txt branch from 93e57c8 to 2cdb5de Compare May 19, 2026 23:02
@story645 story645 linked an issue May 19, 2026 that may be closed by this pull request
Comment thread doc/sphinxext/gallery_order.py Resolved
Comment thread doc/sphinxext/gallery_order.py Resolved
Comment thread doc/sphinxext/gallery_order.py Resolved
Comment thread doc/sphinxext/gallery_order.py Resolved
Comment thread doc/sphinxext/gallery_order.py Resolved
This adds support for a file "gallery_order.txt" in gallery folders for specifying the display order or examples.

Advantages compared to the previous order approach:
- Orders are now defined inside each gallery and not in a central list
- The placeholder '*' allows to put some examples at the front, some at the end, and all others alphabetically sorted in the position of the placeholder
- Checking of entries that do no exist as examples
- Checking that all examples are listed (if no placeholder is specified)

Co-authored-by: Elliott Sales de Andrade <quantum.analyst@gmail.com>
@timhoffm
timhoffm force-pushed the doc-gallery_order-txt branch from 5b55da7 to bc2d2ed Compare June 4, 2026 09:09
@QuLogic QuLogic added this to the v3.11.0 milestone Jun 4, 2026
@QuLogic
QuLogic merged commit 46b5b03 into matplotlib:main Jun 4, 2026
24 checks passed
@timhoffm
timhoffm deleted the doc-gallery_order-txt branch June 4, 2026 18:58
timhoffm added a commit that referenced this pull request Jun 4, 2026
…714-on-v3.11.x

Backport PR #31714 on branch v3.11.x (DOC: Add file-based listed gallery order for examples)
story645 pushed a commit that referenced this pull request Jun 5, 2026
Forgot to add this file in #31714.

This maintains the order that has been there before.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Documentation: build building the docs Documentation: devdocs files in doc/devel Documentation: examples files in galleries/examples Documentation: plot types files in galleries/plot_types Documentation: tutorials files in galleries/tutorials

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[MNT]: Specify ordering in file in gallery folder

2 participants