but to be a bit more helpful, I'd see this as an extension of #234 ...if folks are cool with it (and personally I am as long as it doesn't add much complexity), I think the solution should be similar to what's in there so that we don't have too many different ways of accomplishing the same kind of thing...

I think this would encourage the use of sphinx-gallery for more narrative or tutorial-style galleries

FWIW I think this would be better handled by a custom (toctree-like) directive e.g. at the level of the README.txt (as this is closer to the actual place of usage, rather than hidden within an already lengthy conf.py). Something like

.. examples::

   foo.py
   bar.py

Allowing for skipping files could then be done with a directive option, e.g.

.. examples::
   :allow-missing:

   foo.py
   bar.py

(I certainly support the feature request, of course.)

Well I would argue that the subsection ordering should also be done using rst syntax, so I would generate something like https://sphinx-gallery.readthedocs.io/en/latest/auto_examples/index.html using

Gallery of Examples
===================

General examples
----------------

.. gallery::

   using_sys_argv.py
   plotting_exponential.py
   ...

The sin function
----------------

.. gallery::

   plotting_simple_sin.py
   ...

Examples which don't produce image output
-----------------------------------------

.. gallery::

   ...

which seems way more explicit.

(Well that would not support :allow-missing: but that wasn't supported to begin with :-))

I would just get rid of the old way.

Actually, the toctree even has a globbing facility (http://www.sphinx-doc.org/en/stable/markup/toctree.html), so we could likewise even get rid of filename_pattern in favor of

.. gallery::
   :glob:

   examples/*

The "old way" was only released in 0.12 (i.e. yesterday), so it can't be that widely used.
(Deprecating filename_pattern would cause much more pain and would be a completely different story.)

but to be a bit more helpful, I'd see this as an extension of #234 ...if folks are cool with it (and personally I am as long as it doesn't add much complexity), I think the solution should be similar to what's in there so that we don't have too many different ways of accomplishing the same kind of thing...

Indeed controlling the examples ordering within a subsection was in the back of our mind in #234 (this is part of the reason #234 took some time) so that is the way I would go for. The idea would be to have an additional key like within_subsection_order (better naming more than welcome) and pass in a sort key to it. This solution is fully generic provided that the the paths that get passed to the sort key contain the top folder, e.g. tutorials or examples in the sphinx-gallery case. ExplicitOrderKey can already be used for @Eric89GXL use case.

Indeed we had examples ordering in vision. And I strongly support using a sortkey in this case as well. I don't want nevertheless to mix it with the subsection order sortkey, it should be independent.
The reason for making it independent is that at the examples level, there is more information in place. And thus we sort under criteria beyond what is included in the filename. (To keep compatibility with scikit-learn we sort by amount of code)
My idea is to extend the current list where we hold the thumbnail information to have the entries

[(full_example_path, amount_of_code, rst_thumbnail), ...]

Then the sortkey can sort this list. full_example_path allows for alphabetical sort, or used to deduce any other property of the file, like size, modification time, etc. Or being explicit about the files, we can still sort by amount_of_code to keep current default.

My opinion against Sphinx directive. They are not so simple to develop nor maintain, and our testing framework is not advanced enough to have tests for them(although I'm trying to improve on the test system). But above all, Sphinx seems to make breaking changes in their API or internal code on every release and it is quite a pain to keep up on those changes and then make patches for the various versions. I want to avoid that maintenance burden on features we can do without relying on Sphinx internals.

Indeed we had examples ordering in vision. And I strongly support using a sortkey in this case as well. I don't want nevertheless to mix it with the subsection order sortkey, it should be independent.

😕 I was advocating having a separate key within_subsection_order (or a better name). How is that mixing it with the subsection order key?

And thus we sort under criteria beyond what is included in the filename. (To keep compatibility with scikit-learn we sort by amount of code)

If you have the filename you can figure out the amount of code inside the file to mimic the current behaviour, can you not?

@Titan-C I thought there was some consensus on this and I am slightly puzzled that we are still debating it. I feel I have already made this argument but I 'll make it again: simplicity and ease of use. You can customise the "between subsection ordering" and the "within subsection ordering" in a similar manner.

For completeness' sake, this is what I have in mind:

sphinx_gallery_conf = {
    ...
    'subsection_order': ExplicitOrderKey(...),
    'within_subsection_order': AlphabeticalOrderKey()
    ...
}

@lesteve I missunderstood your first comment. I also have in mind what you put in your code example. 2 separate entries with separate sortkeys.

If you have the filename you can figure out the amount of code inside the file to mimic the current behaviour, can you not?

Yes you can. But you need to read the file again to infer that. On the other hand that is a value we have already evaluated. Said that, multiple reads of the same file have been a common pattern in our codebase and does not affect performance to much.

@lesteve I missunderstood your first comment. I also have in mind what you put in your code example. 2 separate entries with separate sortkeys.

Great to hear that!

On the other hand that is a value we have already evaluated. Said that, multiple reads of the same file have been a common pattern in our codebase and does not affect performance to much.

Agreed, in most cases opening the file multiple times is going to be peanuts compared to running the example inside the file.

I agree w/ @lesteve and @Titan-C - before I was suggesting we should use a similar solution to the one that we did with folders (e.g. using a sorting key, list of folders, something like this), but I agree that it should not be the same thing.

AlphabeticalOrderKey seems ambiguous, maybe AlphabeticalFilenameOrderKey and AlphabeticalTitleOrderKey (current default, right?).

I know that filenames get passed to the sort key (probably not obvious to any user of course), so AlphabeticalOrderKey sounds fine to me. This is the first name that came to mind so better suggestions welcome.

Note the default is length of the example (number of characters or lines in the file, I can't remember) of the as a proxy of "example complexity" so simple (i.e. short) examples come first. You'll need to find a nice name for this one as well ;-).

• If it was just AlphabeticalOrderKey, this means it could be used either for file names, folder names, etc. It'd just need to be clearly documented how you could use this.
• LineLengthKey sounds like an easy name to me :-)

+1 on a PR, I think this is a logical extension of functionality

If it was just AlphabeticalOrderKey, this means it could be used either for file names, folder names, etc. It'd just need to be clearly documented how you could use this.

Great point!

FWIW at the moment the "amount of code" is computed by generate_file_rst here.

I must say that the default ordering for strings in Python is case sensitive and alphabetical. Thus such default would go as None, which is already the case for alphabetically sorted subsections, no need to invent a new name. I would only worry about the amount of code key.

I'm OK with that as long as we document the "python default" case :-)

I thought about None, but this feels a bit too magical to me. On top of that, within_subsection_order: None feels too much like there is no order rather than an alphabetical one.

The sorting key is straightfoward to implement (not tested):

class AlphabeticalOrder(object):
    def __call__(self, item):
        return item

None is indeed too magical. And after looking at the CI fails of PR #278, I see we'll need to give it a name and use a more elaborate function to handle the paths and filenames to all the examples.

good point @lesteve !

Okay I'll incorporate these ideas when taking over #278

you are on a roll right now @Eric89GXL !!!