DOC: Sort gallery subsections by filename #11214
Conversation
|
This was added in sphinx-gallery 0.1.13, so you need to bump the minimum version in the requirements. |
3dd9ce8 to
09f6f5a
Compare
|
Good point. I added this to the |
|
|
09f6f5a to
0dad4dc
Compare
|
I suppose this is beter. It'd still be nice if we could order them ourselves somehow... |
|
I mean we could order them by using consistent filenames. Or by using a clear structure for the titles (and then use another sphinx-gallery sorter). We could also writer our own sorter, but on what would it need to sort? |
|
I mean we could just have an index.rst in the directory... |
|
... at some point one would then need to question how useful sphinx-gallery really is. Now we're already adding backreferences manually, next, we're creating the gallery by hand... |
|
its been discussed 😉 |
There was a problem hiding this comment.
For the examples this is an improvement, even though not optimal.
For the tutorials, this is equally bad, e.g. the first introductory tutorial should be the usage guide. We should manually define an order for the tutorials in some way.
Anyway, approving as better than before.
|
We should just number the file names of the tutorials. I assume it’ll sort on numbers. Suggest %03doldname.py. just in case someone gets ambitious |
|
Not sure that enforcing an order by a filename convention is good. This means that I have to rename the files in case I want to reorder them or add another tutorial. This also affects the url and would break existing links on the web. |
|
I agree with @timhoffm here. We do not want to rename any files and we do not want to break any links. But we do want to have control over at least some of the subsection orders, e.g. in the tutorials. I think there is a solution to this. I will prepare a new PR later tonight or tomorrow. |
|
Good points! Would you like this merged or did you want to wait on your new PR? |
|
See sphinx-gallery/sphinx-gallery#275 (comment) for my thoughts on the topic... |
|
It seems there is |
|
I posted an alternative to this PR in #11257. This would allow custom ordering where necessary. The "thoughts" by @anntzer to use rst toctrees does not seem feasable (currently); they would need to come from the sphinx-gallery side. The idea by @jklymak to number the examples themselves would be doable, but has the drawback to clutter the titles with numbers and makes it hard to change a once determined order in case a new example should be positionned between two existing ones. I think the alternative in #11257 might be a good compromise for now. |
|
Closing in lieu of #11257. Feel free to reopen if that doesn't work out |
PR Summary
Up to now the subsections of the gallery were sorted by the length of the code section(s) in the respective example. This let the gallery look a bit chaotic.
Instead it might be useful to sort the examples within each subsection by the filename of the example. This would still not give perfect thematic ordering, but since in many cases the filenames start with the name of the function they focus on, some kind of basic ordering would be achieved.
Note that an alternative would be to order by example headline/title. This seems not too useful because we can have the examples named like "A bar plot...", "Bar plot...", "Demo for Bar..", "Subplots with bars" etc.
This PR would introduce ordering by filename, since it seems to be the best one can achieve automatically and without renaming half of the examples.
PR Checklist