What's the scope of this site?

[pradyunsg]

Moving this out of a merged PR, so that it's more visible and easier to reference in the future.

The first motivation of sphinx-themes.org is to publish as many themes as possible. Otherwise, I wouldn't have had to do such a large amount of work. My idea is that even if the theme is old or not maintained, I want to publish it as it is because someone might be inspired by it. I also want to show that there are so many themes in Sphinx, even if they are mixture of good and bad.

Also, I do not have a solid axis of what is a good theme and what is a bad. That's why I don't want to "curate".

Originally posted by @shirou in https://github.com/sphinx-themes/sphinx-themes.org/issues/73#issuecomment-838409250

[pradyunsg]

Ah buggery. I thought I'd already posted a three paragraph long response to this. I sure do remember writing one. I guess, I'm bedridden by an ear infection, so... here's a longer version of that.

The first motivation of sphinx-themes.org is to publish as many themes as possible. Otherwise, I wouldn't have had to do such a large amount of work.

I totally understand. This site genuinely made things more discoverable and I'm grateful that you did the work.

Personally, my experience from the rewrite was that that it was a lot of work to get the old and outdated themes working with the rewrite (and many of them still didn't -- they just built with oddly-broken sites), I don't think that the effort needed to properly account for the unmaintained stuff is worth it in any way.

I think a long list of every Sphinx theme (maintained, unmaintained, working, broken) is not useful to anyone who is going to visit the site. I'd go so far as to say that it's actively harmful, similar to how dead wood is harmful for a tree. They increase build times, make the site load slower, make the generated site larger and make it more difficult to find the genuinely useful stuff.

From what I can tell, there can be three audiences for this site:

• Someone shopping for a theme. Presenting a long list, where the "good stuff" is mised with unmaintained themes just makes it more difficult to find a good theme.
• Someone evaluating Sphinx as a documentation engine (and whether they should use it): A whole bunch of unmaintained themes being presented on the page gives them the feeling that Sphinx itself is unmaintained and doesn't have an active community. I think this site has the opportunity to present Sphinx in the best light and we should do that.
• Someone scouting for ideas for their own theme. I think this is the group you're trying to cater to with the long list? IMO fhis is by far the smallest audience and I don't think they benefit from the dead weight either. More on this below.

My idea is that even if the theme is old or not maintained, I want to publish it as it is because someone might be inspired by it.

I understand. I don't think "providing inspiration" needs all the themes out there to be listed on the site though -- a substantial portion of the themes were basically unmaintained forks of ReadTheDocs' theme. The company / project changed one wanted to rebrand for their (usually commercial) project and then let the code languish. Those could serve as inspiration, if you didn't need to triage to the larger portion that didn't actually change anything other than the package name. Or it wasn't actually published using an OSI approved license by the company.

These unmaintained/for-my-company themes are also generally bitrotten -- at some point, they will not work with newer Sphinx versions, especially as Sphinx is being updated more frequently and is actually making backwards incompatible changes now (like any other piece of software).

Also, I think it's increasingly unlikely that most authors of newer Sphinx themes would look at prior really-old Sphinx themes for design inspiration -- I certainly didn't. I expect the sources of inspiration would come from things on the modern web, rather than the past Sphinx themes. There's a lot of non-Sphinx documentation stuff available that looks like it belongs on the modern web and that was actually written/maintained the last 5 years by web developers -- most Sphinx themes don't look like they were written in this decade.

Also, I do not have a solid axis of what is a good theme and what is a bad. That's why I don't want to "curate".

I'd like to think I have a good sense of that. I really really want to curate at least a part of the site -- every audience I noted above benefits from a curated list of "good themes".

Shoppers will get the themes that they likely care about on the top of the list. Exploring-Sphinx folks will be shown the best of Sphinx, rather than the long tail legacy (AKA dead stuff) from being a mature software ecosystem. Looking-for-inspiration folks will be exposed to the "good stuff" that Sphinx has, to draw inspiration from and don't need to triage through 10s-100s of almost-the-same themes.

From the Twitter responnses I got when I tweeted about this, people generally agreed that the curated list was much nicer than the long list we used to have.

If you're not comfortable being a curator of the site, I'd be more than happy to remove your name from that. That said, if you don't mind, I would really like to have your username presented on the site -- you're a big part of why this site exists and you're also the person paying the domain name costs!

[shirou]

ok, I understand.

I unfortunately agree with your opinion that most of the themes are not updated or are from some company. I also agree with your concern that such themes might make people feel uneasy about the Sphinx ecosystem.

In other words, I agree with "curated". But I just want there was an explicit policy about theme selection.

For example, a policy like the following (The numbers are values I just came up with)

• To add a theme, open a PR or Issue. Then add it when it has two or more +1s.
• If the theme has not been updated in 5 years, or has been downloaded less than 10 times in a year, open the issue and remove the theme after 3 months

I think it would be appropriate for a democratic organization if there were clear policy like this.

[pradyunsg]

I just want there was an explicit policy about theme selection. it would be appropriate for a democratic organization if there were clear policy like this.

While I understand this, I also don't want to try to solve a problem we don't have yet.

I like to avoid adding process/policies if we don't need to -- and IMO we can do that here. We already have fairly rough guidelines in https://github.com/sphinx-themes/sphinx-themes.org/blob/master/CONTRIBUTING.md#guidelines, which is based on the issues we've had already (or technical limitations).

I don't think having any sort of strict rules would help make decisions on any of the incoming requests or PRs -- let's handle the requests as they come. If we see a common pattern across them or a need for clear policy, let's figure out the policy then -- based on what we learn from those requests. We'll know what problem we're trying to address with that policy, which will help us come up with a good policy.

[shirou]

Sorry for late response, and, I see. I understand. Lazy evaluation is better. Fortunately (unfortunately?), we haven't received so many requests.

[pradyunsg]

Closing this out then, since we seem to be in agreement about the status quo. We can revisit this, if things change. :)