Wish: ordering of example gallery (and sphinx table of contents)

A nice to have is the ability to specify an ordering for example directories and examples within them. While this is trivial to do by prefixing with numbers, this breaks any existing URLs. Perhaps we can conceive of a way to specify order.

On Sunday, June 07, 2015 02:12:08 AM jnothman wrote:

A nice to have is the ability to specify an ordering for example directories
and examples within them. While this is trivial to do by prefixing with
numbers, this breaks any existing URLs. Perhaps we can conceive of a way to
specify order.
Honestly the current ordering for the examples within each folder is done by
the amount of lines of code each file has. It can be possible to implement an
ordering function and pass it during the configuration step.

Reply to this email directly or view it on GitHub:

#37

�scar N�jera

This is something I would really like to see in a future update. Being able to have specific examples first would be fantastic. I saw the proposed alphabetical sort, and was wondering if a better solution might be extracted from an optional part of the python filename.

It would indeed be useful to have a variety of options, including alphabetical sorting, and more explicit way. +1 for a pull request.

I reckon there are two different orderings that you can implement:

between folders ordering, controlling the order of the sections in the gallery.
within folder ordering, controlling the order of the examples within a given section.

In my mind 1. has an immediate use case, in nilearn we renamed the examples 01_foo, 02_bar, 03_baz to control ordering of the gallery sections, which is hacky to say the least.

2. is useful to have but maybe not as critical I would say. The current ordering by number of lines (as some kind of proxy for example complexity) is fine with me. Having said that 2. is probably easier to implement since we already have an explicit sorting in the code.

This one has passed through some discussion and changes within the
repository as well. We changed from file size, to alphabetical, to net
line of code ordering.

I'm still unsure how to expose this feature to the user.

Should the user implement his own sorting function?
Should the user provide an explicit list of the examples order?
Something else?

Should the user implement his own sorting function?

Should the user provide an explicit list of the examples order?

That sounds brittle, though an option.

Something else?

Well, at least have a few options, such as lines of code and alphabetic,
that are set by an option in the conf.py

curious if there is any new development on this idea. a few folks here are interested in implementing sphinx-gallery for their projects but want to know if they can choose the ordering of images in the gallery

What I'd like to do is explicitly list the ordering in the README.txt file. That way I'd also have more fine-grained control over which scripts in a given gallery folder are actually included (i.e. if a script is temporarily broken or something like that). If that sounds reasonable I'd be happy to take a shot at implementing this.

No progress on this, PR more than welcome!

Just to be clear I think we are talking about within section ordering, i.e. bullet point 2. in #37 (comment).

I would be fine with a custom function that can be specified in conf.py. I would say we should implement the functions that users are most likely to use:

number of lines of the code snippet (which is what we do at the moment as a proxy to try to put "simple" examples first)
alphabetical order
ordering by explicilty listing the examples in the way the user want them ordered, which is what the last two comments are about IIUC.

That way I'd also have more fine-grained control over which scripts in a given gallery folder are actually included (i.e. if a script is temporarily broken or something like that)

I don't think this is a good use case of the ordering functionality. You can already control which example are being run through sphinx_gallery_conf['filename_pattern'] in conf.py (see this for more details) . Also for temporarily broken examples, you can list examples that are allowed to fail if you want to exit with a 0 exit code (e.g. in a CI environment), see this for more details.

I'd be +1 for letting devs provide a function that accepts a list of filenames, and outputs a list representing the order they should be displayed in a gallery.

I would be in favour of a sorting key, similarly to the key argument you can pass to sorted.

That assumes the filename is enough/appropriate information to build a sort key from...

…

On 9 March 2017 at 09:36, Loïc Estève ***@***.***> wrote: I would be in favour of a sorting key, similarly to the key argument you can pass to sorted. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#37 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAEz66Hz3FW6evCuz7eR4eSRWLkYc846ks5rjy2FgaJpZM4E6u39> .

That assumes the filename is enough/appropriate information to build a sort key from...

Yes that is the assumption, do you have a use case where the filename is not enough ?

Another ping on this issue as it's coming up in a matplotlib discussion. What if there were a gallery_order keyword in the SG configuration? This could be a function that will be passed a list of strings corresponding to the gallery folders, and must output a list of strings where set(lista) == set(listb) and len(lista) == len(listb).

I suppose the filename can always be a key to a lookup of priority

…

On 24 Apr 2017 10:26 am, "Chris Holdgraf" ***@***.***> wrote: Another ping on this issue as it's coming up in a matplotlib discussion. What if there were a gallery_order keyword in the SG configuration? This could be a function that will be passed a list of strings corresponding to the gallery folders, and must output a list of strings where set(lista) == set(listb) and len(lista) == len(listb). — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#37 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAEz62xc70d-yQm6_r24y3AsLHyE24rpks5ry-wogaJpZM4E6u39> .

What if there were a gallery_order keyword in the SG configuration? This could be a function that will be passed a list of strings corresponding to the gallery folders, and must output a list of strings where set(lista) == set(listb) and len(lista) == len(listb).

I guess you are talking about between folders ordering, i.e. 1. defined above in #37 (comment).

A rough sketch of what I had in mind:

class ExplicitOrderKey(object):         
     def __init__(self, ordered_list):
         self.ordered_list = ordered_list
    def __call__(self, item):
         return self.ordered_list.index(item)

key = ExplicitOrderKey(['b', 'c', 'a'])
sorted(['a', 'b', 'c'], key=key)

You could have a better error message in case an item is not in self.ordered_list (use case: new folder of examples was added without changing conf.py). We could provide the ExplicitOrderKey (with hopefully a better name) somewhere in sphinx_gallery. The sorting key would be defined in conf.py. You then need to add the key argument to sorted here and possibly here for consistency.

A PR is more than welcome.

ok cool - I can try to get to this once I get the current PR merged in matplotlib (trying to merge things earlier than later, and then improve stuff iteratively later on). It would definitely be a benefit for MPL, I think.

This ticket should be closed.

Closed via #234

Navigation Menu

Repository navigation

Wish: ordering of example gallery (and sphinx table of contents) #37

#37

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Wish: ordering of example gallery (and sphinx table of contents) #37

Description

Activity

Titan-C commented on Jun 7, 2015

#37

Samreay commented on Aug 17, 2016

GaelVaroquaux commented on Aug 17, 2016

lesteve commented on Aug 17, 2016

Titan-C commented on Aug 17, 2016

GaelVaroquaux commented on Aug 17, 2016

choldgraf commented on Mar 7, 2017

ngoldbaum commented on Mar 8, 2017

lesteve commented on Mar 8, 2017

choldgraf commented on Mar 8, 2017

lesteve commented on Mar 8, 2017

jnothman commented on Mar 8, 2017

lesteve commented on Mar 9, 2017

choldgraf commented on Apr 24, 2017

jnothman commented on Apr 24, 2017

lesteve commented on Apr 24, 2017

choldgraf commented on Apr 24, 2017

NelleV commented on Jul 21, 2017

choldgraf commented on Jul 21, 2017

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions