Categorization and tagging

maximlt commented 1 year ago

The examples are currently displayed without being categorized. Each examples can have labels, displayed as badges in their card (e.g. holoviews, panel), these badges aren't tags like one can find on a blog, that would link to a page referencing all the posts having that tag.

I'm putting categorization and tagging into the same issue as, if we have to work on categorizing the different examples, we might as well add tags. But really my main goal here is categorization of the projects, I consider tags to be nice to have but not fundamental.

Categorization

On the categorization front, I suggest we define a set of categories that are relevant for the examples. This list of categories will live in dodo.py (or in a dedicated file, but I made sure dodo.py was easily importable so it should be fine ther). Its order will matter for how the categories end up being displayed. Each project will have to define a category entry it its examples_config spec (I'd also be fine with categories, taking a list, if we think that projects can belong to multiple categories). The category found in the project file will have to be already listed in the list of categories, there will be a linter for that. New projects that think they warrant the creation of a new category can do so, they just need to add their category in the main list. Somewhere (in conf.py, dodo.py or a dedicated file), a list of the Featured projects will be set. That list will be taken to dynamically create a new category, that will be displayed before all the other categories.

The options to visualize these categories are:

using simple tabs, like Bokeh does
using simple vertical sections, like the current Panel Reference Gallery
having each category part of the top-level TOC so that they're all displayed in the navigation bar
some fancier approaches, like on this ReactJS gallery

I would probably be in favor of the simple tabs approach. IMO it would look nicer than the vertical sections, and is probably pretty straightforward to implement vs. any fancier approach. A few potential limitations with tabs:

I don't know what happens if we have too many tabs (note that this should also be checked for small screens)
There's currently no way to link to a specific tab (PR being reviewed that implements that https://github.com/executablebooks/sphinx-design/pull/104)

The nav bar approach is interesting as it would mean that the categories would always be displayed on your screen, making it easy to move from a category to another. However this doesn't work well if we end up with many categories, and the PyData Sphinx Theme is currently quite limited in its ability to customize the nav bar (see https://github.com/pydata/pydata-sphinx-theme/issues/944, https://github.com/pydata/pydata-sphinx-theme/issues/1016 and https://github.com/pydata/pydata-sphinx-theme/issues/1061), that is now just inherited from the top-level toctree (plus optional external links).

By the way, the discussion around the nav bar should also take into account that it's currently (with the PyData Sphinx Theme) not possible to have all the projects in any toctree, as given the structure of the repo (all projects put in the doc folder, e.g. doc/projname) this means that the PyData Sphinx Theme would display them all in the nav bar! Apparently this was not a problem with the PyViz theme. To deal with that I've got a hack that injects a customized toctree in the gallery index.rst file generated by NBSite, this isn't ideal.

Current site with the PyViz theme, you'll note even if this project has multiple files they are not listed in the side bar.

Same problem with the current dev site:

Any approach would require changes to NBSite, even the vertical section one as the layout of the projects in the repo is all flat and NBSite expects it to be structured to build a gallery (I think).

Tagging

Having an automated system for managing tags and building indexes will require more work than what needs to be done to set up categorization. We could draw some inspiration from the ablog sphinx extension with which you can manage a blog, and that handles tags.

There are already some actions we can do, before having any system at all:

already adding tags in a tags entry in the examples_config tag. I think tags should be free-form, a linter could just let you know when you add a tag that is new.
defining what badges should be shown in the gallery. It's currently a mix of holoviz packages, some other packages (e.g. networkx), conda channels and others (there's a dev label).
another easy win would be to turn the gallery badges into links

Integration

When a project only updates its category or tags, this should not trigger the project test and build on the CI, it should only build the docs.

The new function that infers Last Updated from the last commit date in a project folder will be affected by that, maybe it should just ignore the anaconda-project.yml. Also the new function that detects which projects changed (using git diff) will need to be updated.

jbednar commented 1 year ago

That all sounds good. Tabs seems fine to me!

maximlt commented 1 year ago

Found on Twitter a site built on top of the Pydata-Sphinx-Theme that supports tags and has an example gallery. Lots of inspiration to draw from it for sure!

Link to the site: https://docs.rapids.ai/deployment/nightly/examples/index.html#

It has a tags filter pane in the main side bar:

Each example has its tags displayed in the secondary side bar, clicking on a tag sets it as a URL query param and directs you to a gallery of the examples filtered by this tag. Neat.

https://github.com/rapidsai/deployment/pull/121

holoviz-topics / examples