@timhoffm wanted it to be a gallery_order.txt file, I think the best thing is maybe make it configurable - possibly w/ fallback:

Look for gallery-order, then sort-order directive in readme, then the explicit lists in gallery_order?

If we're parsing the readme files, there needs to be some sort of comment/fake directive/(possibly real directive but that's out of scope here) to set off the file list so it doesn't get rendered as part of rendering the readme.

Also thanks for taking this on!

So selfishly I want this to go in b/c I want to make use of this once sphinx-gallery/sphinx-gallery#1226 goes in. Can you add move one of the explicit file lists to a readme to show that this function works?

I don't think the ordering should be defined in README, instead we should create a GALLERY_ORDERING.txt. See sphinx-gallery/sphinx-gallery#1068 (comment).

I don't think the ordering should be defined in README,

I think in README the ordering would need to be set off with a pseudo-directive so it doesn't get rendered as part of the README. I think the easiest thing for this PR to implement is parsing a gallery_order.txt file

I'm a bit confused on what the issue should be addressing now. My current implementation falls short as you said there's no real comment in the galleries README as well as I'm unable to find other files. I'm happy to show you what results I have as of now which will be in the gallery_order.txt under galleries.

I'm a bit confused on what the issue should be addressing now

Sorry, should have been more detailed in the original issue. I'm gonna give the example of the plot types gallery. The way the gallery subheadings are ordered:

Is currently determined by this list in gallery_order.py:

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

And subsection ordering is determined by:

list_all = [
    ...
    # **Plot Types
    # Basic
    "plot", "scatter_plot", "bar", "stem", "step", "fill_between",
    ...
    ]

I'm happy to show you what results I have as of now which will be in the gallery_order.txt under galleries.

This is on the right path, but the idea is that under plot_types/ for example, there would be a gallery_order.txt file that has a list of folders:

basic
stats
arrays
unstructured
3D

and for example under basic/ there would be another gallery_order.txt that would do a subsection sort, for example:

bar.py
scatter_plot.py
plot.py
UNSORTED
fill_between.py

that lists the beginning and end plots.

And those files could be read into a list kind of like the one in gallery_order.py and used for ordering the sub galleries. The parent folders should be equal to the Path('gallery_order.txt`).parent and therefore don't need to be listed in the file.

These lists of files are fed into MplExplicitOrder and MPLExplicitSubOrder and that turns them into sorting keys used to sort the thumbnails. (I also should also add the unorderd implementation to MplExplicitSubOrder but really those classes can probably be consolidated as they've got the same call method->just instantiate them with different base lists but also I'm gonna say out of scope here...

totally optional

The totally not necessary proposal for readme is that in a readme.rst file you can set off the ordering using a comment/fake directive, so for example in the plot types readme:

.. _plot_types:

.. redirect-from:: /tutorials/basic/sample_plots

Plot types
==========

Overview of many common plotting commands provided by Matplotlib.

See the `gallery <../gallery/index.html>`_ for more examples and
the `tutorials page <../tutorials/index.html>`_ for longer examples.

.. gallery-sort-order::
   basic
   stats
   arrays
   unstructured
   3D

If it's not stashed in a comment, then rst will try to parse/build it as if it was plain text and we don't want that content on the readme.

ETA: when I say fall back, what I mean is that you can set it up so that sort order is determined by:

1. gallery_order.txt
2. if not in gallery_order.text then check readme .. gallery-sort-order::
3. if not in .. gallery-sort-order then check ordering list in gallery_order.py

And the only reason I'm proposing fallback is then transition from one sorting scheme to the other can be done in follow up PRs

closing in favor of #27991 because that's a more robust solution