Add sorting

[choldgraf]

Right now this website is useful to get a comprehensive view of many Sphinx Themes. However, I suspect that the vast majority of people that land on the site are more interested in narrowing their list of possible Sphinx themes, rather than expanding it. The current number of themes, and large variability in quality, makes it really hard to get useful information from the website if you're trying to narrow down your search.

This process could be helped if there were basic abilities to re-order the themes in this list. For example, being able to do these alone:

• Sort by GitHub stars
• Sort by date last-updated
• Sort by date created
• Sort by date last-released

Would massively boost the signal-to-noise of the website (in my opinion, one of them might even be the default view). Is there any chance this functionality could be built into the site?

This is also related to #24 though I think would be much simpler to implement.

[pradyunsg]

I'm on board. I don't know how we'd get some of this data, because the site isn't being rebuilt on a regular basis and doing the data-fetch + ordering from the user's browser seems... like a bad idea?

[choldgraf]

Well FWIW, the approach we take with gallery.jupyterbook.org is to just re-build the docs on a github-actions CRON job (daily), and randomize the entries each time. We could do something like that. Though may wish not to randomize. I'd be a fan of just sorting by 'latest release date' for each. You could grab that from the PyPI API at build time and sort entries that way.

[mgeier]

• Sort by GitHub stars

I think this would be quite unfair against themes that are hosted elsewhere.

For reference, the ordering could be something like this: https://github.com/search?o=desc&q=sphinx+theme&s=stars&type=Repositories

• Sort by date last-updated

This might be hard to obtain, since themes may be hosted wherever.

• Sort by date created

If this is available from PyPI, this might be interesting for seeing the "newest" themes.

However, very new themes probably tend to not be listed on sphinx-themes.org, which would make this a bit questionable.

• Sort by date last-released

That sounds like the most meaningful metric to me!

[akhmerov]

The date of latest update on pypi could be a useful github-agnostic criterion. Aside of the ordering, just showing basic metadata (version number/latest release/source link) would already be useful.

[pradyunsg]

Honestly, I'm not sure we need this sort of sorting anymore.

It'd have made more sense when we had literally 100+ themes (given that 80% of themes were an outdated fork of sphinx-rtd-theme that never got updated after the name change). With #72 and #73, that's no longer the case.

Right now, it's easy enough to maintain a list of "featured" themes, and just proactively trim themes that are straight-up bad. To be clear, I do think it'd be neat to have this stuff, I don't think we need it as much as we used to.

I'm tempted to close this TBH, on the basis of "status quo is fine; when we have more 10+ themes being actively maintained, then we'll come back to this". I'll hold off on clicking that button for now though. :)

[pradyunsg]

(I'll dump my notes here none the less, so that future me or someone else has one less thing to do)

The potential PyPI-related metrics for sorting:

• Downloads in last X days -- it's easy enough to get this data from https://pypistats.org/
  • https://pypistats.org/api/packages/furo/recent?period=month
  • data.last_month
• Last release date -- it's possible to get this too from PyPI's JSON API
  • https://pypi.org/pypi/furo/json
  • releases[info.version][0].upload_time

Aside of the ordering, just showing basic metadata (version number/latest release/source link) would already be useful.

This is doable from the PyPI JSON response, but IMO this information should go into the generated sample documentation; not into the gallery view.

[choldgraf]

I think that makes sense - though I also think there's danger in having a hand picked "featured" subset without clear criteria for how things get picked. I don't think it'd be a huge issue, but feels like a potential source of inequity or confusion in the future

[pradyunsg]

I mean... Arguably, there's already bias involved in the ordering. That's basically why I've added "curated by ..." on the site. I wanted to make it clear that whatever biases come through are mine (at least so far), and I am assuming that no one shows up with a pitchfork for the choices I'm making. I'd like to think those are reasonable choices. :)

feels like a potential source of inequity or confusion in the future

Yup, and when we get there, we'll move to these metrics.

[choldgraf]

For sure - i don't have a problem with bias (necessarily anyway) as long as it is explicit instead of implicit

[pradyunsg]

Closing on the basis of: status quo is fine; when we have 10+ themes being actively maintained, then we'll come back to this.

[dantownsend]

I know this issue has been closed for a while, but I was having a similar thought today.

It wasn't clear to me what the ordering was, until I looked at the code.

As already mentioned, I think it would be useful to be able to sort by last updated, popularity, or just plain alphabetical.

Anyway, just my two cents :)

[pradyunsg]

That should get clearer once #24 adds the relevant tags. :)

[choldgraf]

I just want to note that I had the thought once again today that it would be better to sort by last-updated instead of alphabetically. The reason for this is because I noticed that there was a theme called the piccolo-theme, which looks nice and modern and is updated somewhat frequently:

• https://piccolo-theme.readthedocs.io/en/latest/

However, it is way down below the fold in the sphinx themes gallery, and I doubt many people will notice it when they start seeing lots of themes that haven't been updated in a long time and look quite outdated in between the top and where piccolo lives.

This led me to think that the best sorting would be by "last updated", if only because it will boost the signal for themes that are under active development, and for which the author may want more attention / users / etc.

So in my opinion, even if there is no 'interactive' or 'user-selectable' sorting, it would be better if we sorted by last release, rather than by name

[dantownsend]

Yeah, I spent a lot of time developing the Piccolo theme, and it was very discouraging to see it buried down at the bottom of the page, even though it's fairly new and well maintained.

[choldgraf]

hah - for the record, it is completely coincidental that you happened to be the one who already commented on this thread, and that I happened to notice the Piccolo theme 😅

[dantownsend]

It's a small world in Sphinx-land!

[choldgraf]

Could the sort-json.py script use the PyPI package JSON API to grab the date of the latest release, and use that as a sorting key?

e.g., here's the link for the book theme: https://pypi.org/pypi/sphinx-book-theme/json

It's only a few dozen packages, and only runs once a day or so...hopefully that wouldn't be too much extra traffic on pypi but if so then maybe it could be run in a CRON job every week or something and update a local file?

[pradyunsg]

Whoops! #64 moves piccolo to be a featured theme. Sorry about missing that one!

Could the sort-json.py script use the PyPI package JSON API to grab the date of the latest release, and use that as a sorting key?

sort-json? No -- that's checking that the JSON file itself is sorted in a certain fashion. Since the date of latest release keeps evolving, we'd haave the pre-commit check keep failing.

OTOH, this is something we could do client-side. PyPI really doesn't care about the additional network traffic (it's all at a caching CDN layer, and doesn't actually hit PyPI's backends).