New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
jnothman opened this Issue Jun 7, 2015 · 19 comments

Comments

Projects
None yet
8 participants
@jnothman
Contributor

jnothman commented Jun 7, 2015

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.

@Titan-C

This comment has been minimized.

Member

Titan-C commented Jun 7, 2015

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

@Samreay

This comment has been minimized.

Samreay commented Aug 17, 2016

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.

@GaelVaroquaux

This comment has been minimized.

Contributor

GaelVaroquaux commented Aug 17, 2016

@lesteve

This comment has been minimized.

Contributor

lesteve commented Aug 17, 2016

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.

@Titan-C

This comment has been minimized.

Member

Titan-C commented Aug 17, 2016

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?
@GaelVaroquaux

This comment has been minimized.

Contributor

GaelVaroquaux commented Aug 17, 2016

  • 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

@choldgraf

This comment has been minimized.

Contributor

choldgraf commented Mar 7, 2017

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

@ngoldbaum

This comment has been minimized.

ngoldbaum commented Mar 8, 2017

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.

@lesteve

This comment has been minimized.

Contributor

lesteve commented Mar 8, 2017

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.

@choldgraf

This comment has been minimized.

Contributor

choldgraf commented Mar 8, 2017

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.

@lesteve

This comment has been minimized.

Contributor

lesteve commented Mar 8, 2017

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

@jnothman

This comment has been minimized.

Contributor

jnothman commented Mar 8, 2017

@lesteve

This comment has been minimized.

Contributor

lesteve commented Mar 9, 2017

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 ?

@choldgraf

This comment has been minimized.

Contributor

choldgraf commented Apr 24, 2017

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

@jnothman

This comment has been minimized.

Contributor

jnothman commented Apr 24, 2017

@lesteve

This comment has been minimized.

Contributor

lesteve commented Apr 24, 2017

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.

@choldgraf

This comment has been minimized.

Contributor

choldgraf commented Apr 24, 2017

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.

@NelleV

This comment has been minimized.

Contributor

NelleV commented Jul 21, 2017

This ticket should be closed.

@choldgraf

This comment has been minimized.

Contributor

choldgraf commented Jul 21, 2017

Closed via #234

@choldgraf choldgraf closed this Jul 21, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment