Tags for the example gallery?

[NicolasHug]

Just throwing out the idea...

We have lots of examples in the gallery. Some of them are beginner oriented like #15706, and some are much more advanced, like the ones proposed in #14300. It can be overwhelming for newcomers who don't necessarily know what they're looking at.

How would you feel about adding tags, e.g. "Beginner", "Advanced", "New in 0.XX" etc.? I'm picturing these as labels e.g. on the rendered image in the gallery, but we could also use them for filtering?

I guess this is not just scikit-learn related but also a sphinx-gallery feature, I'm just testing the water here first

[glemaitre]

This looks like a great idea. I see also another pattern: "Usage" where we show basic usage, "Tutorial" which an end-to-end example. I thought that we should rework the indexing in the example landing page but I think your proposal would be the best first step (tags + filtering).

[jnothman]

I like this. I've been thinking about the distinction of examples showing algorithmic or ML concepts from those demonstrating usage... But the distinction is blurred and I do expect a challenge to find consensus on the taxonomy. What is the UI/UX proposal?

[adrinjalali]

Kinda related, I guess, is that I'm always lost when I try to find a specific example, or find something which would help. For instance, going to the GridSearchCV, there are tons of examples linked in the bottom, but most of them are not GridSearchCV tutorials really. I guess it would be nice if we could somehow group them better? Not sure.

[jnothman]

Having invented that listing of examples below the estimator, I apologise for it not being optimally helpful (but I still find it can be really really helpful!). ;) But the point of that feature is that it does not require any manual annotation. How do you see tags ameliorating that issue, Adrian? Do you envisage a way to remove the default association with GridSearchCV from a specific example?

[adrinjalali]

I think we can put everything which hasn't been annotated to belong to a category, in the "everything else" category, and put it after the ones we manually tag.

BTW, I do think the feature you've invented is way way better than not having it, and it's pretty okay in most cases. It gets confusing if a class is used in too many examples.

[GaelVaroquaux]

A not too complicated (but imperfect) suggestion for reorganizing examples:

• We could do 2 galleries (sphinx-gallery now supports multiple galleries):
  • "Tutorial examples", where we move the most didactic examples and expand them. Using "notebook style examples" enables to be very didactic
  • "Snippet examples" (don't know if it's a good name), where everything else goes.
• We would put more focus on the "Tutorial examples" by:
  • Putting them more visible on the website
  • Having two backlink minigalleries at the bottom of API documentation, with the first one being examples from the tutorial examples, and the second one being snippets
• Because this reorganization will break links (eg from Google), hence we should keep the same links for the "snippets", which will be most of the examples, and do redirect pages (possibly manually) for the tutorial examples that we move.

I think that the suggestion above would be an intermediate step that would still provide a tangible improvement.

[NicolasHug]

I think that the suggestion above would be an intermediate step that would still provide a tangible improvement.

Agreed!

[lucyleeow]

Possibly interesting/relevant here, a small package for adding tags to sphinx documentation: https://github.com/melissawm/sphinx-tags
I think there is no inherent, easy way to add tags in sphinx.

[glemaitre]

@lucyleeow @jnothman proposed a POC long time ago: https://github.com/scikit-learn/scikit-learn/pull/17929/files

Indeed, we can use the rst_prolog where we define the tag in pure HTML and sphinx will replace it on the go.

It would avoid having an additional dependency in this case.

[lucyleeow]

This is nice! I think the extra functionality that would be nice to add for example gallery tags is to be able to get a list of all examples with a specific tag, I guess similar to the filtering of parameters suggested as an extension (in #17929).

Agree that extra dependency is not ideal but it was also reference to see one way it could be done.

[glemaitre]

If we want to have a better integration as you suggest, then having the dependency would be worth IMO.