Remove Wyrm? Move to something else?

[Blendify]

Since Wyrm is an abandoned project maybe we should consider using something else? This will likely not going to happen for a while but would like to throughout the idea of moving to something like bootstrap. If there is a general approval I could make a proof of concept of moving to bootstrap and keeping the design style as much as possible.

https://github.com/snide/wyrm

[jessetan]

Sounds like a good idea for future proofing, but not a pressing matter.
The current design is probably quite influenced by the choice for wyrm, so when moving to a different framework there will need to be discussion on how much of the current look and feel should be kept (which may require some shoehorning) or if some visual changes are acceptable or desired.

[davidfischer]

I know @agjohnson has some strong feelings here.

I agree this is not pressing but there are a number of advantages to using a common framework (eg. bootstrap, foundation, pure) from developers being more familiar with it, easier for contributors, to better docs of the framework itself.

I do see this as a breaking change. Anybody who has added any raw HTML blocks that rely on any wyrm CSS classes will be broken. That isn't a deal breaker but it is something to consider. Another thing to note is that a lot of newer frameworks have dropped support for older IE versions specifically. Based on a look in our GA, IE<=10 is ~0.11% of our traffic so that is probably ok.

[mitya57]

Bootstrap would be much more familiar to potential contributors and people who want to extend the theme (or add raw HTML blocks). So while it breaks the compatibility right now, it seems a much more future proof solution.

[agjohnson]

So I don't necessarily think the underlying framework is limiting us much in developing this theme. We can probably work around the fact that wyrm is unmaintained if we need Neat 2. The theme is entering maturity though and to replace everything here would create far more problems, for us and for many downstream projects, than it would solve. For that, I'm -1 on a rewrite.

I think what you're describing is a new theme though. This is something I've thought about -- what I'd change, what new design patterns docs are using, etc. There are a lot of modern docs that take our cake in terms of usability and visual appeal. Rewriting this theme in another framework would be making a lot of work for ourselves for marginal gains at best, but it also could be effort that we're instead spending creating something new.

Going forward, RTD can't hold on to this theme/design as a relic of good design. It's showing it's age, and though some of this can be addressed here, some of this likely can't be addressed without ripping out a lot of prior design. I definitely wouldn't start a new framework in bourbon or wyrm, I agree 100% on something maintained and more adopted -- bootstrap and semanticui both support themes, something we'll likely want lest we have no visual distinction between us and the millions of bootstrap/semanticui sites already in circulation.

I do see this as a breaking change. Anybody who has added any raw HTML blocks that rely on any wyrm CSS classes will be broken. That isn't a deal breaker but it is something to consider.

Also, our paying customers often override templates/CSS in our theme. This would cause fallout for them, so they'll likely be stuck on an old version of our theme. If the gains were greater I could justify this position, but I don't see many gains to be had.

[Blendify]

I see your point and I agree that it would be best, if we do this, to develop a new theme. For another project I work on, we will probably stop using this theme and move to a boostrap based version. If this does happen I would be happy to share the bare bones of the project with RTD that we can use to style to a RTD liking. Also in a bigger design it would be great if this new theme and the design of the RTD hosting frame work share a similar design.

[Blendify]

For anyone interested I began initial work on this new theme here: https://github.com/Blendify/sphinx-bootstrap-basic

[davidfischer]

One thing worth talking about it what we hope that a new theme will do that this one doesn't. I have a few things on my wish list:

• It should be easier for doc authors to style the theme. That can mean a variety of things but I think a good starter is to look at Alabaster's customization docs. I think the options are a bit overkill but there should probably be easy "how-to" guides on adding a logo, changing the fonts, and changing colors at least.
• Part of the above is to choose a more widely used front-end framework
• I do not believe that the theme itself should have any RTD specific code. No {% if READTHEDOCS %} blocks.
• A new theme should extend off of an existing theme like the basic theme.

Feel free to chime in with what you think a new theme should do. I think talking about what we hope to get from a new theme will guide the discussion and development process.

[agjohnson]

Also, just to clarify, this is still going to be our primary point of development for our theme. I do see a large benefit in having multiple themes that are the same quality as this theme. However, this theme will remain our default theme unless at some point we happen to create something that surpasses rtd_theme with respects to usability, customization, and design. Currently, we don't have plans to start this work though.

Priority for us on the theme is ensuring this theme continues to address usability issues as much as possible, so rewriting is a bit antithetical to that.

[eric-wieser]

In the meantime, is it worth maintaining a fork of wyrm to deal with bugs like #484?

[jessetan]

Patching individual issues in the theme sounds better to me.

[Blendify]

I started on a bootstrap implementation here: #1055

[stsewd]

Semantic UI hasn't seen commits for 2 years: https://github.com/Semantic-Org/Semantic-UI/branches

From #1055 (comment)

I brought that to the team, and looks like there are plans to swap to https://github.com/fomantic/Fomantic-UI if needed. Also, they put things in next rather than master https://github.com/Semantic-Org/Semantic-UI/tree/next, but it's true that there isn't a release since a long time.

[polyzen]

There is also Bulma which is quite popular and uses "modern features" and no JS:
https://bulma.io/alternative-to-bootstrap/

[Daltz333]

Is there a particular reason against bootstrap?

[Blendify]

I don't know however, given it's popularity and several extensions already available that are also based on bootstrap I think it's the best option.

[ericholscher]

We discussed this above, and it seems the general agreement was to create a new theme. Moving this theme to a different framework would be almost impossible to do without massive backwards incompatibilities.

#544 (comment)

[Blendify]

Shall I create a new repository and copy stuff over and include some of my breaking changes? I would be willing to spend some of my time working on this. Here is my current plan:

• Copy things over
• Implement my work so far on bootstrap and font awesome 5
• Continue refining what I have started and work towards a version that is mostly visually identical to the current theme
• Refactor templates to inherit more templates from sphinx
• Work on creating a refreshed visual identity

Some targets for the new theme:

• HTML5
• Boostrap 5 (not yet released but has nice features such as RTL support and remove jquery)
• Font Awesome 5
• Using latest sphinx, dropping older versions

For the new theme I want to know if we can create a release schedule that matches sphinx, as in when a new version of sphinx is released we create a release. We use version numbers that match sphinx 1:1.

This isn't required but its an idea I had.

[Daltz333]

I think that is a good idea blendify. One thing I'd keep in mind is minifying resource usage and keeping thoughts toward future maintainability.

[Blendify]

Here is a basic mock-up of what I have envisioned for a new theme the major thing to take away is the blocking. The typographing and padding can be refined later.

[agjohnson]

We discussed this above, and it seems the general agreement was to create a new theme. Moving this theme to a different framework would be almost impossible to do without massive backwards incompatibilities.

@Blendify caught up with me on IRC last night, and the Bootstrap migration is a lot closer than I thought. It looks like the RTD live preview isn't loading some of the assets, but locally the theme is much closer to parity than the hosted preview lets on:

This definitely reshapes my opinion of migrating away from Wyrm a fair deal. We weren't interested in migrating to SUI specifically, but the work required to port this theme to any framework was a lot to take on and would end up being fairly low priority for core team. With this work already being fairly mature by the looks of it, I am much less adverse to taking on work around a migration away from Wyrm.

The concerns about backwards incompatibility are still very valid though. There are a lot of themes that have either forked this theme or have extended it via Sphinx theme packaging, and I could definitely see a bootstrap-based theme release breaking a number of user and customer themes.

So, because of this, I think core team needs to discuss priority around supporting a backwards incompatible release first. We'll also want to include theme maintainers on a discussion about the technical decisions. I told @Blendify that I'd check in with the rest of the team and start these conversations, so we avoid blocking the migration PR forever.

[stsewd]

@agjohnson we need to install the project in order to see a correct preview of the current code of the theme, that's fixed with #1039

[agjohnson]

@stsewd pr build preview with the local package was already working for a while, with this: https://github.com/readthedocs/sphinx_rtd_theme/blob/master/docs/conf.py#L20-L21

What in #1039 is required to make live preview work? That seems like an unrelated issue.

I don't see generated assets in the bootstrap PR, which is probably why the live preview looks very broken -- it's using the generated css based on wyrm.

[stsewd]

What in #1039 is required to make live preview work? That seems like an unrelated issue.

the install package step, otherwise it collides with the theme installed by default.

[agjohnson]

the install package step, otherwise it collides with the theme installed by default.

Could you clarify what you mean here? Is this an exception?

[stsewd]

the install package step, otherwise it collides with the theme installed by default.

Could you clarify what you mean here? Is this an exception?

both packages are in sys.path at the same time, when installing using pip it will remove the old package first, so sys.path points to only one path.