DOC: Improve internal sphinx13 style

[timhoffm]

While a systematic update of the theme would be desirable, that's quite a large topic, and will likely not happen any time soon.

This PR adds a few changes to the theme to make it more readable and visually more appealing. In particular:

• Slightly increase the font weight of headings (300 --> 400). These have been quite thin and tended to blend into the surrounding text. The increased weight makes sections a little more distinct.
  Note: The need of this seems to depends on the font used. But generally, 300 is quite thin (normal weight would be 500) and thus IMHO not too well suited for a heading.

• Adapt the color of the search box border to sphinx-blue. Up to now, it had inherited the green from the basic style, which does not fit.
  old:
  

  new:
  

• Add horizontal bars between the components of the side bar. This makes the separation between local ("On this page") and global ("Site navigation") more clear.
  

• Re-style admonitions to use colored title backgrounds. The colors make the kind of admonition more clear. Up to now, all admonitions looked similar.
  old:
  

  new:
  

[chrisjsewell]

This looks great thanks!

While a systematic update of the theme would be desirable, that's quite a large topic, and will likely not happen any time soon.

Completely agree the theme needs updating 👍
I think Sphinx's own docs should be the "gold standard", and at the moment it is certainly lacking

Do you have any time/desire to work on more improvements, or ideas you would like to share?

I feel like essentially it would be great to work towards having a "built-in" https://pradyunsg.me/furo and/or even https://pradyunsg.me/lutra

[timhoffm]

Do you have any time/desire to work on more improvements, or ideas you would like to share?

I feel like essentially it would be great to work towards having a "built-in" https://pradyunsg.me/furo and/or even https://pradyunsg.me/lutra

I believe, #10419 covers most aspects well:

• The default theme shold be better, the sphinx site should be better; ideally the sphinx site should use the default theme (We may deviate though: The default should work for simple docs, maybe the sphinx site is too large so that another layout is better. But in that case, both should be visually similar)
• Writing a good theme takes substantial effort (UX, accessibitlity, configurability, ...)
• We have backward compatibility requirements.

In all, this makes is quite difficult to move forward. I think the pragmatic approach is:

• Add some minimal incremental improvements (quick wins like this PR) to sphinx13 so that the sphinx site looks a bit better. - It should be usable and should not scare away users.
• Concentrate on one default builtin theme. We have 10 builtlin themes, but they have all aged and I would not recommend any of them nowadays. The core project has at most the capacity to develop/maintain one theme. Let's mark everything else as legacy (not recommended / not further developed).
• I don't think though that sphinx13 or the default theme can be modernized completely through incremental changes. Likely a fresh start is needed, e.g. with adopting sphinx-basic-ng (Update the web theme used in Sphinx' documentation #10419 (comment) and following). I believe this can be done in a backward-compatible way as sphinx-basic-ng still builds on basic.
• Help current users to get decent looking docs. Minimal incremental improvements to the default theme as quick wins. We should still cummunicate that this is only a basic versions and there are more refined third party themes (https://sphinx-themes.org/). Maybe even recommend some for different use cases (furo, pydata-sphinx, book).

I believe half of the task is proper documentation and communication (current state, best practices, etc.).

[chrisjsewell]

Add some minimal incremental improvements (quick wins like this PR) to sphinx13 so that the sphinx site looks a bit better. It should be usable and should not scare away users.

Indeed. Just to know, do you have in mind / intend to create PRs for any more improvements?

Concentrate on one default builtin theme. We have 10 builtlin themes, but they have all aged and I would not recommend any of them nowadays.

yeh exactly, I don't know if anyone really uses them anymore 🤷

[timhoffm]

Indeed. Just to know, do you have in mind / intend to create PRs for any more improvements?

W.r.t. sphinx13 style, I have aggregated the most obvious improvements into this PR. I have no concrete further plans.

There are some other improvments that users would benefit from, in alabaster (default theme), sphinx doc content, and the result of quick-start. I will be able to submit them over time, but I have enough to do so that I don't plan a systematic involvement.