-
Notifications
You must be signed in to change notification settings - Fork 2k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Many old themes are broken #11931
Comments
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.
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. |
@mgeier I think this should be tagged |
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. |
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. |
Just to put a couple of things into perspective:
|
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 |
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. |
Well, as I said:
I don't know if people want to still use those themes. 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.
I'm not saying anything is anyone's fault. 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 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. |
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 #11931 (comment):
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 A |
All the more reason to trim those old themes? #10672 |
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.
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.
The text was updated successfully, but these errors were encountered: