sphinx
sphinx copied to clipboard
sphinx-doc
Many old themes are broken
Describe the bug
It is of course not the responsibility of the Sphinx maintainers to fix broken themes, but maybe there can be some backwards-compatibility effort to avoid some breakage?
How to Reproduce
Look at https://sphinx-themes.org/.
If I counted correctly, 10 of the themes are broken.
This is of course the problem of the individual themes, but I think it also shines a bad light on Sphinx itself if so many themes are broken.
Environment Information
n/a
Sphinx extensions
No response
Additional context
Of course, those broken themes could be repaired (unlikely) or they could be removed from https://sphinx-themes.org/, but maybe someone still wants to use them?
I personally don't want to use any of them, so for me, removing them from the list would also be fine.
it also shines a bad light on Sphinx itself if so many themes are broken.
At first sight, agreed! Not only is it potentially misleading incurring in users wasting time with outdated themes, but it gives the wrong impression of the gallery's (and Sphinx's) maintainers not caring.
or they could be removed from https://sphinx-themes.org/, but maybe someone still wants to use them?
A smart solution would be putting some sections into the page and ordering the themes in descending order of supported Sphinx version. That way the gallery keeps an historical timeline showcasing Sphinx themes' evolution over time.
I agree that we need to be more careful (especially after #11608). One of the issue is that many things that appear to be public but are actually not meant to be exposed even with a 'public' name. So when refactorization happens... sometimes we break things because we thought they wouldn't be used externally.
Also, I don't know whether the themes being broken are still maintained or not and/or whether they should pin their sphinx version.
OK, I have tagged it "html theme", though I must confess I don't understand the semantics of this tag.
It could mean "built-in html themes" or "html theme api". Latter would be appropriate here.
I don't understand the semantics of this tag.
Looking at the created "labels" (tags) as a whole, leads me to think it's a "catch all" label since more specific labels weren't created.
I'd like to join the call for a change in heart from the maintainers. I'm sure Sphinx is a frustrating codebase from the bad old days of Python but you simply can not break backwards compatibility to the rate you have been over the past few years.
If at all possible please try and refactor by adding new interfaces while allowing old ones to work as-is. If that can't be done, consider a python2->python3-esque migration with a sphinx2. And we all saw how the py2->py3 migration went: it nearly killed Python itself! Backwards compatibility is that important and forcing your users to put in migration effort just to tread water is really that bad.
When you churn your codebase like this it requires the entire community to spend increasing effort on remediating what was once a working Sphinx configuration. Public places like this sphinx-themes.org website are just the tip of the iceberg. Your users, after spending their initial time investment with getting Sphinx up and running, were hoping that investment would "pay off" with functional, stable docs for years or maybe even a whole decade. If they later incur excessive maintenance effort the Sphinx investment loses its justification. The churn that broke sphinx-themes.org is just a reflection of the fact that people don't have time to put into fixing and maintaining what was once a working docs setup and what you're seeing on sphinx-themes.org is what is happening across the entire Sphinx user base. This is a wakeup call that you've pushed the needle too far.
@dgilman
The churn that broke sphinx-themes.org
Just to put a couple of things into perspective:
- The themes that come bundled with Sphinx are all still supported afaict (except one, where the author said he wasn't interested in continuing the project). Some 3rd party themes might have been abandoned by their authors, but read on...
If they later incur excessive maintenance effort the Sphinx investment loses its justification.
- In theory, changing the theme for an end-user can be as simple as changing one single line in
conf.py, namely:html_theme. Users wanting to customize a theme beyond its default settings should know their docs become theme dependent.
When you churn your codebase like this
- Afaict Sphinx keeps with the Python life cycle. At 5 years/version we could summarize the theme dependency to 1 line/5 years which seems pretty good by any metric.
I don't understand - if this is about the Sphinx-themes site, why don't you report this to https://github.com/sphinx-themes/sphinx-themes.org/issues ?
Sphinx breaking themes that haven't been touched in 5+ years is hardly Sphinx fault, IMHO
Your users, after spending their initial time investment with getting Sphinx up and running, were hoping that investment would "pay off" with functional, stable docs for years or maybe even a whole decade
No, you can't expect that from us. In general, if you want stability, you pin the versions of the packages you are using. In addition, Sphinx decided not to have any backports since backporting some features is extremely hard. One issue on the theme side is that they don't put an upper bound on their sphinx version, causing them to use outdated variables (AFAICT, the reason why the themes fail is the same, namely a variable name that does not exist).
Now, I admit that some things were breaking changes while we were still in a minor version (like what we had in 7.2.0), so when you say "these past years", it should be more "these past months". Also, major versions are allowed to introduce breaking changes, and most of the time we try to make keep the public API (namely the externally documented API and not the internally one) as stable as possible. There is unfortunately a lot of confusion about whether something is public or not because of how we named things back then.
I don't understand - if this is about the Sphinx-themes site, why don't you report this to https://github.com/sphinx-themes/sphinx-themes.org/issues ?
Well, as I said:
or they could be removed from https://sphinx-themes.org/, but maybe someone still wants to use them?
I don't know if people want to still use those themes. But I would assume there are still people who want that.
That's part of the reason I have opened this issue. If it turns out that those themes are not relevant anymore, I'm willing to create an MR to remove them from https://sphinx-themes.org/. That's really not the problem. But I honestly don't know if they are relevant or not.
But it's really not about this specific site, it's more about if we can provide some backwards compatibility.
Sphinx breaking themes that haven't been touched in 5+ years is hardly Sphinx fault, IMHO
I'm not saying anything is anyone's fault. I'm just saying that people might be turned off if they see that 20% of the themes are broken (without knowing whose fault any of this is).
And 5 years is really not a long time in this context.
I'm not saying that Sphinx should never make breaking changes, I'm just noticing that there is worrying breakage and I'm wondering if there is some way to retroactively avoid that from Sphinx's side.
If not, that's fine, then we can close this issue, but I think it is worth considering seriously.
I have a suggestion to reduce the number of unnoticed breaking changes. Currently mypy checks how changes affect a corpus of opensource projects. We could do the same by checking whether our changes affects widely-used themes and the bundled themes (I don't remember whether our themes are even checked or not actually).
The drawback is that it might take a long time for that and so I don't know if we should integrate this in the CI/CD directly. I don't know if we can run checks 'just before' squashing/merge and abort that squash-merge if the 'last' tests do not pass.
@AA-Turner any thoughts on that?
If we're worried about people new to open source making bad decisions, then I think a disclaimer in the Third Party Themes section that mentions the risks of going third party vs built-in and how to weight the decision process of picking a theme (time since last release, number of contributors, etc) would resolve a lot of that. "Aggregate" sites like https://awesomesphinx.useblocks.com/ and https://libraries.io/pypi/Sphinx have similar point systems.
That section should probably also mention that https://sphinx-themes.org/ is a third party website.
And to take that a step further, make those metrics for each theme available on https://sphinx-themes.org/ so the decision process is easier.
then I think a disclaimer in the Third Party Themes
The disclaimer should also be included at the top of Projects using Sphinx that ends up being a per theme aggregate.
Are you sure there is nothing that can be done on Sphinx's side here?
For example, the one-line fix in #12351 would (most likely) fix no less than 10 themes on https://sphinx-themes.org/. This would leave only 3 broken themes (which I'll probably look into at a later time).
Writing the same as I did on #12351:
This went through the standard deprecation policy, I am hesitant to reverse it all simply as old themes are no longer maintained.
Juan-Luis makes a good point in https://github.com/sphinx-doc/sphinx/issues/11931#issuecomment-1926905417:
Sphinx breaking themes that haven't been touched in 5+ years is hardly Sphinx['s] fault
On the linked issue, for example, I haven't seen efforts from those themes to update. We have a fairly conservative compatability policy, which has been advertised for many years now.
The unaffiliated sphinx-themes.org website could consider changing their visual presentation of the failing themes such that all of them are positioned at the end, or hidden by default, which would make the experience less jarring.
A
Survey
basicstrap
- https://pypi.org/project/sphinxjp.themes.basicstrap/
- https://github.com/tell-k/sphinxjp.themes.basicstrap
- Last released: 06 May 2019
bernard
- https://pypi.org/project/sphinx_bernard_theme/
- https://github.com/bernardphp/bernardphp-com/
- Last released: 08 Feb 2014
conestack
- https://pypi.org/project/sphinx-conestack-theme/
- https://github.com/conestack/sphinx-conestack-theme
- Last released: 13 Dec 2021
hachibee
- https://pypi.org/project/hachibee-sphinx-theme/
- https://github.com/hachibeeDI/Sphinx-hachibee-theme
- Last released: 05 Feb 2015
karma
- https://pypi.org/project/karma_sphinx_theme/
- https://github.com/AccentDesign/karma_sphinx_theme
- https://karma-sphinx-theme.readthedocs.io/en/latest/
- Last released: 20 Jun 2018
murray
- https://pypi.org/project/murray/
- https://github.com/wlonk/murray/
- Last released: 08 Jun 2018
redactor
- https://pypi.org/project/sphinx-redactor-theme/
- https://github.com/testthedocs/sphinx_redactor_theme
- https://github.com/makkus/sphinx_redactor_theme
- Last released: 25 Jul 2017
sizzle
- https://pypi.org/project/sphinx-sizzle-theme/
- https://github.com/vsajip/sphinx_sizzle_theme
- Last released: 31 Aug 2023
stanford
- https://pypi.org/project/sphinx-theme/
- https://github.com/DrJimFan/Sphinx-theme
- Last released: 05 Jan 2017
topos
- https://pypi.org/project/topos-theme/
- https://github.com/alcarney/topos-theme
- Last released: 14 Mar 2019
yummy
- https://pypi.org/project/yummy-sphinx-theme/
- https://github.com/TagnumElite/yummy_sphinx_theme
- Last released: 08 Sep 2019
Conclusion
Of these, it seems only https://github.com/vsajip/sphinx_sizzle_theme is actively developed, with commits in the past year. conestack was most recently released 2.33 years ago, and no other theme has had a release this decade.
I have opened https://github.com/vsajip/sphinx_sizzle_theme/pull/20 for sizzle.
A
All the more reason to trim those old themes? https://github.com/sphinx-doc/sphinx/issues/10672