search

sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.55k stars 2.12k forks source link

Update the web theme used in Sphinx' documentation #10419

Open choldgraf opened 2 years ago

choldgraf commented 2 years ago

Context

This issue is not a specific proposal, but I wanted to see if others in the community agree with me here, in the hopes that this might lead to a pathway forward, or explicitly settle the issue as not high-priority.

The Sphinx documentation has an excellent amount of information in it, and is a resource that I regularly go back to in order to learn about the project and its APIs. However because there is a lot of information, it becomes particularly important that this information is easy to navigate and discover different topics.

The website theme for Sphinx was added about 9 years ago. In the past several years, there have been a lot of new developments in both web standards and design/UI expectations, as well as many theme improvements in the Sphinx ecosystem.

For example:

And a lot of other nice themes are demoed here.

Question to discuss

In my opinion, Sphinx would benefit from having a theme that aligns more with how modern documentation sites tend to be structured. This could either be via improvements to its current theme, or adopting another theme that is in the community.

Do others generally agree or disagree that an overhaul of the theme to be more modern would have a large benefit? Has this been discussed before, and / or do others have ideas of what themes could be explored?

More specific issues

Since this issue is fairly broad in its scope, and since there's not consensus on just switching to a community-developed theme, I've opened up a few issues for more specific improvements to make to the current Sphinx theme in case that makes things easier to discuss and track separately:

tk0miya commented 2 years ago

Do others generally agree or disagree that an overhaul of the theme to be more modern would have a large benefit?

+0: I don't have an opinion on this topic. But it does not mean we should not improve our documents.

Has this been discussed before, and / or do others have ideas of what themes could be explored?

AFAIK, this is the first proposal.

jdillard commented 2 years ago

I'm for it as long as stability isn't impacted in a significant way. Seems like a demo using Furo, etc (I'm not familiar with all of those to know which one would be the best fit outside of aesthetics) would be a first convincing step.

benjaoming commented 2 years ago

Made a demo using Sphinx-Immaterial theme here:

https://sphinx-themed.readthedocs.io/en/latest/

Note that the landing page will not work, but if you click around in all the other sections, things look good IMHO -- and this is a vast improvement over the old site, since it clearly communicates that Sphinx is a modern documentation tool (which it is).

benjaoming commented 2 years ago

Added a demo using the Furo theme:

https://sphinx-themed.readthedocs.io/en/furo/

AA-Turner commented 2 years ago

I think it is important that the theme Sphinx uses is maintained in this project -- for example co-ordinating the removal of JS would've been harder if doing so over multiple projects.

I've proposed a refresh of the current theme in #10652 that I'd appreciate comments on.

A

choldgraf commented 2 years ago

In my opinion there are arguments in both directions - I can see benefits to having control over your own theme so that you are more familiar with what it's like to have a custom theme in Sphinx in general. On the other hand, I think many people will assume that the theme the Sphinx documentation uses is also the default theme for Sphinx, since this is what most other major popular documentation engines do (e.g. docasaurus or mkdocs). Given how important good-looking documentation is nowadays, I think Sphinx unnecessarily hinders itself in appealing to many potential users by not having its own documentation follow modern practices in layout and functionality.

Other non-trivial things that I think many users will "expect" out of a modern documentation engine theme, and for which not having these things may be a dealbreaker:

I feel like those three things above are becoming more and more common across documentation sites, so even if Sphinx doesn't change its theme, that might be a good target to shoot for via iterative PRs.

If you prefer to close this issue and instead focus on issues related to improving the current theme, I'm 👍 on that

AA-Turner commented 2 years ago

I agree on most points (I'm not a great fan of 'dark modes', but they do seem quite popular). #10646 relates to improving the basic theme, which underpins all other themes. If you're talking about broader changes than that, please do open a new tracking issue where we can discuss.

I also probably want to look at the default theme at some point -- alabaster is unmaintained and feels a little dated currently, and for the reasons above I'd like to have the default theme be part of Sphinx core.

A

benjaoming commented 2 years ago

re: @AA-Turner :

If you're talking about broader changes than that, please do open a new tracking issue where we can discuss.

Isn't that what this issue is about?

AA-Turner commented 2 years ago

No---this issue is about the theme for Sphinx's own documentation, rather than the themes that Sphinx provides. The changes that Chris is talking about w.r.t. 'modern documentation engines' should be made to all themes, not just for Sphinx's own use.

A

AA-Turner commented 2 years ago

Remaining points before closing this issue:

A

benjaoming commented 2 years ago

The changes that Chris is talking about w.r.t. 'modern documentation engines' should be made to all themes, not just for Sphinx's own use.

I hope that I get the misunderstanding here: Is it an implicit prerequisite that Sphinx documentation/website must use the basic/sphinx13 theme? Or that those two must be one and the same? Because I think that it's fair to make that a part of the discussion?

I would ask: Can the Sphinx documentation/website benefit from abandoning the sphinx13 theme and starting a journey with a new and modern theme?

Btw, the recent changes to sphinx13 made by @AA-Turner are great, I hope that a discussion about other themes does not discourage from improving sphinx13 directly. Those sorts of improvements can be received without being stalled by discussion, which makes them great.

My opinion as an outsider: From my own experience with the costs of frontend development, I think that odds are against being able to go all the way to getting sphinx13 up-to-speed and as modern as the alternative community themes.

I think that it's a shame that the Sphinx website doesn't give users the same great experience of state-of-the-art community themes. As I've said before, it risks making new users think that Sphinx itself is outdated (which it is not).

AA-Turner commented 2 years ago

I hope that I get the misunderstanding here: Is it an implicit prerequisite that Sphinx documentation/website must use the basic/sphinx13 theme?

Sphinx is set up so that all themes inherit from the basic theme. So any improvement made to basic propogates outwards to the other themes.

Do we need to use sphinx13? No. But if we are making changes to improve the themes, I think it is unfair to users of Sphinx to do so 'selfishly' and only change the theme that isn't actually distributed with Sphinx -- personally I think there should be a stable of great default themes included with Sphinx, rather than saying 'use Sphinx, but all the themes are terrible, so you also need to choose a third-party one'. We should make the default theme great, and also improve the theme for Sphinx's docs (perhaps Sphinx's docs could use such a great default theme).

A

choldgraf commented 2 years ago

I agree with this suggestion that Sphinx wants to have its own excellent documentation out of the box, I am fully in support of this. Though it doesn't want to get too opinionated, and I think that it should treat its developer community as a strength to leverage, not a weakness because those developers aren't doing everything in Sphinx core.

I'm concerned that creating a whole new theme that is modern within Sphinx will also be difficult for two reasons:

  1. Creating and maintaining a theme with modern design and UX is a lot of work, and Sphinx has a lot of other stuff to do as well
  2. Sphinx's basic theme templates need to be relatively unopinionated and can't change much, or they will break all of the downstream themes when they change

I'd also point to projects like sphinx-basic-ng which are attempts to modernize the "skeleton" and base of the Sphinx theme. I'm not sure if it makes sense for that to be in Sphinx core or not, but it's probably worth exploring why @pradyunsg felt it needed to exist outside of Sphinx rather than in the core library.

pradyunsg commented 2 years ago

Ah, I thought I'd responded here already!

The motivation for basic-ng being developed outside of Sphinx is that it's currently moving at a much faster development cadence that Sphinx itself. Beyond that, Sphinx has a somewhat stringent backwards compatibility policy, that would make development of something like basic-ng within Sphinx much harder; since those constraints would reduce the ability to walk back on design choices we find to be poor, especially in this early development phase.

pradyunsg commented 2 years ago

I'm totally on board for improving Sphinx's basic theme, as much as we can, and if we'd pull in any bits and pieces from basic-ng, that'd be great as well.

Personally, I was gonna propose this once Lutra was stable and once sphinx-book-theme or pydata-sphinx-theme built upon basic-ng -- mostly to push in the direction of improving the basic-ng design, before triggering discussions about how/what we can change about the basic theme.

AA-Turner commented 2 years ago

Beyond that, Sphinx has a somewhat stringent backwards compatibility policy, that would make development of something like basic-ng within Sphinx much harder; since those constraints would reduce the ability to walk back on design choices we find to be poor, especially in this early development phase.

[^1] Could you add some colour on this point? Whilst the extension mechanism means that we can create such projects outwith the core, I think it is a loss if our policies/culture drive down innovation explicitly or implicitly. What would be the options for change & improvement here? (Appetite for implementation is a different matter, I appreciate).

A

[^1]: This thread is already pretty off-the-initial-topic, so...

pradyunsg commented 2 years ago

I think it's a healthy thing to do. In the curve of popular vs nimble, Sphinx is firmly on the popular end of the spectrum and can't be very nimble. The backwards compatibility approach taken here is acknowledging of that and caters to those constraints well.

I don't think having a strong backwards compatibility policy means that it necessarily stifles innovation -- that comes more from an inability to do things differently or experiment with stuff without those constraints. Sphinx is fine on this front.

For Rust, this takes the form of stable vs nightly builds and what functionality they contain. For Python, the provisional module system provided that. For Sphinx, the extensions system provides that. (For Python Packaging... oops?)

I think they're all well designed approaches, and Sphinx's is pretty healthy here.

tk0miya commented 2 years ago

Do we need to use sphinx13? No. But if we are making changes to improve the themes, I think it is unfair to users of Sphinx to do so 'selfishly' and only change the theme that isn't actually distributed with Sphinx -- personally I think there should be a stable of great default themes included with Sphinx, rather than saying 'use Sphinx, but all the themes are terrible, so you also need to choose a third-party one'.

I don't know why sphinx-doc.org started to use its own theme (a.k.a. sphinx13). But it's much better to use the default theme of its release package instead of it.

choldgraf commented 2 years ago

But it's much better to use the default theme of its release package instead of it.

I think this is true. Most users will assume that the theme the package uses for it's documentation is the same theme they'll get out of the box. As such, I think it's good to use the default theme in the documentation, and make that theme an excellent, not-too-opinionated theme.

One place where this might differ is the fact that most documentation sites are fairly simple and make sense with a single sidebar (eg, furo, rtd theme, book theme). However, the Sphinx docs are more complex and might warrant a header navigation as well (eg, similar to the pydata or lutra theme).

electric-coder commented 2 months ago

However, the Sphinx docs are more complex and might warrant a header navigation as well (eg, similar to the pydata or lutra theme).

I don't see a tangible gain to trying to structure the Sphinx docs to fit into 5 header links as those themes use. E.g. PyData Theme doesn't allow removing the central part of the header which forces a waste of vertical real-estate on every page, so it's not necessarily an advantage.