Get rid of "display" name?

[mgeier]

I think for users those two things are important:

• the exact theme name as used in html_theme
• the exact PyPI package name

Currently, none of them is immediately visible on https://sphinx-themes.org/.

I guess the PyPI name can be inferred from the URL of the examples, but AFAICT the theme name isn't available at all.

I think instead of the "display" name, the html_theme name should be used as the title of the example boxes, but I think adding the PyPI package name to be immediately visible would also be helpful.

What do you think?

[pradyunsg]

I don't think using the html_theme or PyPI name is a good idea. Most of the themes are named something like sphinx_xyz_theme. Mentioning "sphinx" or "theme" in the names in a "Sphinx Themes Gallery" is redundant, distracting, and IMO ugly. I also don't wanna penalize themes that needed to use a name like sphinx-XYZ-theme due to namespacing reasons, or just out of a rough convention established by sphinx-rtd-theme.

Removing "sphinx" and "theme" from the names and capitalizing what's left (for visual clarity) gives us with exactly what "display" is right now. Using a separate key has the added advantage of reduced code complexity, and allowing to more easily account for cases where folks might want something different.

[pradyunsg]

I don't like unclear states so, if there's no response/concerns raised in the next ~8 hours, I'll close this issue. :)

[mgeier]

I'm just thinking about what's helpful to visitors.

If they see a theme they like, how do they know how to use it?

They need exactly two pieces of information for that, none of which is displayed on the page.

Adding those two pieces of information would be a clear improvement, and probably not hard to implement, wouldn't it?

And once those two pieces of information are visible, a third piece of (mostly useless) information (I mean the current "display" name, just to be clear), would only serve to add confusion. But if you think the added confusion (and increased maintenance cost) is justified by something, that's fine, then keep it!

[pradyunsg]

Discoverability is a fair point, but I wanna note that the information is surfaced in a fairly clear manner in the "quickstart" section in the sample documentation.

I'm very wary of trying to convey everything in the same place, or trying to cater to too broad an audience.

As I hinted at earlier, I want things to look good, and "sphinx-book-theme" or "sphinx-rtd-theme" straight up don't look as good as "Book" or "ReadTheDocs" for theme titles. And, I'm not sure the PyPI name there conveys the right information anyway.

There's likely something that we could just better describe in sample-docs/index.rst FWIW, but I had already spent the better part of my weekend on the rewrite, so I wanted to move on to wrapping it up. :)

[mgeier]

I wanna note that the information is surfaced in a fairly clear manner in the "quickstart" section in the sample documentation.

Cool, I didn't see that!

And that means that at least a few other people won't see it, either.

I was just assuming that the content is the same generic content in all samples.

I'm sure it would help to put this on the first page, ideally close to the top.

With that, I think visitors would easily get the information they need, and my above points are mostly moot.

I'm very wary of trying to convey everything in the same place,

The problem is you are adding unnecessary and unhelpful (but good-looking) information and then conveying that.

If you would just not add information, everything would be simpler (from a visitor's perspective).

or trying to cater to too broad an audience.

I don't understand how showing the actual theme name and package name broadens the audience too much.

Do you only want to cater to an audience that does not need this information?

I want things to look good, and "sphinx-book-theme" or "sphinx-rtd-theme" straight up don't look as good as "Book" or "ReadTheDocs" for theme titles.

That's totally a matter of taste, and that's totally your call.

I just want to remind you that "looking good" and "being helpful" sometimes can be in conflict.

And, I'm not sure the PyPI name there conveys the right information anyway.

I think showing the PyPI name alone would be better than the status quo, but still not perfect.

I was thinking about showing both pieces of information right next to each other, probably something like this:

---

sphinx-press-theme (html_theme = 'press')

---

I think this could even include a link to the theme homepage, but this would be additional information and additional maintenance cost. To avoid this overhead, a link to the PyPI package could be used instead.

And an aside about "improving" the displayed name: Each theme author freely chose both the PyPI name and the theme name, but they did not choose your simplified and capitalized name.

I also don't wanna penalize themes that needed to use a name like sphinx-XYZ-theme due to namespacing reasons, or just out of a rough convention established by sphinx-rtd-theme.

They chose that name, they could just as well have chosen a different one. I agree that it's silly to add "sphinx" and "theme" to the name (html_theme) of a Sphinx theme, that's why I simply didn't do it for my theme. I think it's useful to have it in the PyPI name, though, because there it's not true that each package is actually a Sphinx theme.

And if anything is unfair in this case, it's alphabetic ordering, which is always unfair to somebody.

64 might help with that, but I think this is an orthogonal issue.

I had already spent the better part of my weekend on the rewrite, so I wanted to move on to wrapping it up.

I very much appreciate your great work on this. I just think there are still ways to improve the value it provides for visitors.

But all this is of course not urgent ... the site is already great as it is!

[pradyunsg]

I just think there are still ways to improve the value it provides for visitors.

And there always will be!

I'll iterate on the index.rst file and augument the information discovery situation over time, and PRs for this are welcome! :)

---

That said, I don't think that display is "unnecessary and unhelpful" information and won't be getting rid of it. Let's open a separate issue to talk about the whole discoverability thing. :)

[pradyunsg]

78 should improve the things we discussed here (other than the whole "display" stuff). :)