Skip to content
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

[docs] CSS style improvements #12546

Merged
merged 3 commits into from
Jul 14, 2024
Merged

Conversation

timhoffm
Copy link
Contributor

@timhoffm timhoffm commented Jul 11, 2024

As a suggestion:

  • increase paragraph line-height to 1.5 to give text a bit more room to breathe. 1.5 is a common choice in web page typography; e.g. rtd-sphinx-theme, furo and GitHub use this (pydata sphinx theme goes even to 1.65).
  • Don't shrink the text in admonitions. They are equally important and thus should have the same size as regular paragraphs. For reference, e.g. pydata-sphinx-theme and rtd-sphinx-theme do this.
  • Adapt the border color for all warning/error like admonitions. Warnings had a fixed color that did not fit well to the new admonition style.

@chrisjsewell
Copy link
Member

chrisjsewell commented Jul 11, 2024

Don't shrink the text in admonitions. They are equally important and thus should have the same size as regular paragraphs. For reference, e.g. pydata-sphinx-theme and rtd-sphinx-theme do this.

For counter-reference though 😅 : https://pradyunsg.me/furo/kitchen-sink/admonitions/ and https://squidfunk.github.io/mkdocs-material/reference/annotations/, the text is smaller

They are meant to be "asides" semantically, so I don't know if I agree that they are "equally important" (and I think in general furo is nicer looking and maybe better to follow)

If nothing else, the "feature" admonitions on the landing page should still be smaller.

The other changes I think are good 👍

@chrisjsewell chrisjsewell self-requested a review July 11, 2024 12:51
Copy link
Member

@chrisjsewell chrisjsewell left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

see comment

@timhoffm
Copy link
Contributor Author

timhoffm commented Jul 11, 2024

Re: Font size of admonitions:

I believe we're all not experts on typography. I therefore checked what "big sites" do, assuming they have thought about these things.

Note

GitHub does not reduce the font size in admontions.

The same holds for Microsoft Azure docs and Apple developer docs.

Based on that, I propose same-size is likely better, but I don't have a strong opinion.

As a suggestion:

- increase paragraph line-height to 1.5 to give text a bit more room to breathe.
  1.5 is a common choice in web page typography; e.g. rtd-sphinx-theme, furo and
  GitHub use this (pydata sphinx theme goes even to 1.65).
- Don't shrink the text in admonitions. They are equally important and thus should
  have the same size as regular paragraphs.
- Adapt the border color for all warning/error like admonitions. Warnings had a
  fixed color that did not fit well to the new admonition style.
@timhoffm
Copy link
Contributor Author

If nothing else, the "feature" admonitions on the landing page should still be smaller.

Ok, kept them in the smaller font.

@chrisjsewell chrisjsewell changed the title Style suggestions for sphinx13 [docs] CSS style improvements Jul 14, 2024
@chrisjsewell chrisjsewell merged commit 0075803 into sphinx-doc:master Jul 14, 2024
7 checks passed
@chrisjsewell
Copy link
Member

I removed the increase in admonition text size for now, since I really do feel it makes the pages with many admonitions less readable

@timhoffm timhoffm deleted the sphinx13-style branch July 14, 2024 06:48
@AA-Turner AA-Turner added this to the 7.4.0 milestone Jul 15, 2024
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Aug 15, 2024
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants