If you want Sphinx to achieve that breakout success, priority #1 should be to get high-quality, beautiful themes.
At least for me, aesthetics are a high-priority factor when deciding which site generator to use. Hugo and Gatsby have great built-in themes, and I have chosen them for projects before based largely on this fact.
The Sphinx themes here [0] and here [1] are various levels of "meh" to bland.
I don't disagree that themes are an important part of marketing a tool. The engineer in me doesn't want that to be the case, but I recognise that people like pretty things, it makes a difference.
However I'd push back a little. That Fluent UI doc site looks like every other doc site from an open source project started since ~2020 that I've seen, and this means that I have certain expectations: I expect the project to be immature, I expect the docs to be incomplete or out of date, I expect the search to be an annoying AI search that does a worse job than the basic full text search that I expect elsewhere, I expect that to get anything of substance done I'm going to have to hang out on a Discord server. When I see a ReadTheDocs site though with that default theme, I expect the project to be somewhat mature, I expect it to basically work. I expect the docs to be fairly complete.
Are these expectations fair? Not really, but that's the whole point here. Open Source projects are not immune from marketing, and when marketing, what other similar projects do will affect how people respond to your marketing. Nothing exists in isolation.
In my experience, engineers think marketing doesn't apply to them, but these impressions really do matter.
I agree that more stellar, super-visually-appealing themes will help Sphinx get to the next level.
One nit: I called Sphinx a sleeping giant because it's already majorly successful in the Python ecosystem. Pretty much all big Python docs sites are built on top of Sphinx, including docs.python.org. But I think it's fair to say that when Sphinx starts getting major adoption outside of the Python ecosystem then we can start calling it a breakout success.
Apple's site loads for me in under 1 second with a clean cache force-reload.
The featured themes, in general, have poor typography and whitespace, poor formatting and alignment, and uninspired colors and design. Furo [0] is the best-designed of them and would make a solid foundation for a proper theme.
At least for me, aesthetics are a high-priority factor when deciding which site generator to use. Hugo and Gatsby have great built-in themes, and I have chosen them for projects before based largely on this fact.
The Sphinx themes here [0] and here [1] are various levels of "meh" to bland.
Look at the standard Sphinx RTD theme: https://sphinx-rtd-theme.readthedocs.io/en/stable/
Now, compare it to documentation sites like:
- Apple's: https://developer.apple.com/documentation/swift/array
- Fluent UI: https://react.fluentui.dev/?path=/docs/concepts-developer-po...
RTD looks dated in comparison.
[0]: https://sphinx-themes.org/
[1]: https://sphinxthemes.com/#featured-themes