search

sphinx-themes / sphinx-themes.org

A showcase for Sphinx documentation themes
https://sphinx-themes.org
BSD 2-Clause "Simplified" License
236 stars 44 forks source link

Add sorting #64

Closed choldgraf closed 3 years ago

choldgraf commented 3 years ago

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:

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago
  • 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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

(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:

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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

pradyunsg commented 3 years ago

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 commented 2 years ago

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 commented 2 years ago

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

choldgraf commented 2 years ago

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:

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

It's a small world in Sphinx-land!

choldgraf commented 2 years ago

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 commented 2 years ago

Whoops! https://github.com/sphinx-themes/sphinx-themes.org/issues/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).