Wish: ordering of example gallery (and sphinx table of contents) about sphinx-gallery HOT 19 CLOSED

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

from sphinx-gallery.

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.

from sphinx-gallery.

from sphinx-gallery.

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

1. between folders ordering, controlling the order of the sections in the gallery.
2. 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.

from sphinx-gallery.

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?

from sphinx-gallery.

• 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

from sphinx-gallery.

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

from sphinx-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.

from sphinx-gallery.

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.

from sphinx-gallery.

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.

from sphinx-gallery.

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

from sphinx-gallery.

from sphinx-gallery.

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 ?

from sphinx-gallery.

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).

from sphinx-gallery.

from sphinx-gallery.

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.

from sphinx-gallery.

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.

from sphinx-gallery.

This ticket should be closed.

from sphinx-gallery.

Closed via #234

from sphinx-gallery.