You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
[MNT]: Specify ordering in file in gallery folder #25032
Since we wrote this extension to do the ordering, there's no reason we can't change it to read from README.txt in each directory. We could have it look for something that looks like a comment to reST so it does nothing in the sphinx-gallery-processed reST without having to do anything extra. Originally posted by @QuLogic in #24746 (comment)
I think it's a relatively good first issue following #25028 because each readme can be parsed into its respective gallery list. Steps involved are
figure out the reST comment notation that allows for easy specification of ordering + a consistent sentinel for placing unsorted files
write a parser that translates the set of comments into a list that preserves the order (including sentinel)
Medium difficulty because some familiarity with sphinx would be helpful, but not strictly necessary. I think a medium to advanced version of this would be implementing a .. gallery-toccustom directive
And yes, down the line we should maybe spin a maintain docs page off from the writing docs page.
An alternative to using the readme is using a special purpose 'gallery_order' file #24746 (comment)
I looked into this yesterday; it's not particularly difficult to implement, and I did about half of it. The subsection order is pretty easy to do as each one is independent, but the problem with the higher section order is that we currently have a mix with some special things appearing after the unsorted ones. I did not fully investigate if the ordering class gets access to all the directories but I don't believe so, so there's a little bit of extra work to handle the bookkeeping of the split there.
I want to do this issue, but I am a little bit confused by this part:
write a parser that translates the set of comments into a list that preserves the order (including sentinel)
Are you pulling the text from each README.md or reordering the directory? Thank you!
We have a declarative order specification in there. Given that changes to the gallery order are are, an order file in the gallery doesn't seem to bring much additional benefit. And I'm reluctant to add more complex logic that we'd have to maintain.
Given that changes to the gallery order are are, an order file in the gallery doesn't seem to bring much additional benefit.
Yeah, I'm fine closing this and maybe repopening if there's a change to the docs where it'd be really useful to order by file and can't just use the sphinx minigallery command to do it.
Activity
jklymak commentedon Jan 19, 2023
I was going to open a discussion with sphinx-gallery about this as well. It seems like something they should be able to handle.
QuLogic commentedon Jan 19, 2023
I looked into this yesterday; it's not particularly difficult to implement, and I did about half of it. The subsection order is pretty easy to do as each one is independent, but the problem with the higher section order is that we currently have a mix with some special things appearing after the unsorted ones. I did not fully investigate if the ordering class gets access to all the directories but I don't believe so, so there's a little bit of extra work to handle the bookkeeping of the split there.
[-][MNT]: Specify gallery ordering in readme[/-][+][MNT]: Specify ordering in file in gallery folder[/+]Higgs32584 commentedon Mar 10, 2023
I want to do this issue, but I am a little bit confused by this part:
write a parser that translates the set of comments into a list that preserves the order (including sentinel)
Are you pulling the text from each README.md or reordering the directory? Thank you!
Fix matplotlib#25032 for plot_types
Minor edit in README for clarity (matplotlib#25032)
Kruthikakatta commentedon Dec 20, 2025
I’d like to work on this issue.
timhoffm commentedon Dec 20, 2025
@story645 Is this still needed / worth the effort?
Given the constrains of sphinx-gallery due to their ordering logic, https://github.com/matplotlib/matplotlib/blob/main/doc/sphinxext/gallery_order.py isn't too bad.
We have a declarative order specification in there. Given that changes to the gallery order are are, an order file in the gallery doesn't seem to bring much additional benefit. And I'm reluctant to add more complex logic that we'd have to maintain.
story645 commentedon Dec 22, 2025
Yeah, I'm fine closing this and maybe repopening if there's a change to the docs where it'd be really useful to order by file and can't just use the sphinx minigallery command to do it.
parthivdholiya77-coder commentedon Jan 28, 2026
Hi, I am new to open source and would like to work on this issue.
Can you please guide me on where to start?
timhoffm commentedon Jan 28, 2026
This is closed. No action planned.