-
-
Notifications
You must be signed in to change notification settings - Fork 4.3k
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
Furo docs theme with styling #23159
Merged
Merged
Furo docs theme with styling #23159
Changes from all commits
Commits
Show all changes
56 commits
Select commit
Hold shift + click to select a range
4b00be3
Disable SymPy Live
bertiewooster 76fe2de
Undo adding furo to release/requirements.txt
bertiewooster 11fad9a
Using theme furo
bertiewooster 4923df3
Added furo to doc/requirements.txt
bertiewooster 71d1814
Commented out html_style to build Furo
bertiewooster f5ae2cf
Removed default.css_t to disable custom styling
bertiewooster bbe3269
Restyle the Furo theme
asmeurer c0c8579
Some more fixes to the docs theming
asmeurer 33c4a02
Move the Furo custom CSS variables back into html_theme_options
asmeurer fc63639
Disable the fancy scrolling behavior in the Furo theme
asmeurer 0df6af6
Make the headings in the API docs easier to see
asmeurer 6152880
Reduce the blockquote padding
asmeurer e49b7bb
Some more improvements to the documentation styling:
asmeurer 42a39e9
Use a slightly less bold font for the API doc subheaders ("Examples" …
asmeurer 93d2808
Add a GitHub icon to the docs footer
asmeurer ddc654b
Remove background color from blockquotes
asmeurer e21952e
Slightly dim the background color of code blocks in light mode
asmeurer 802270c
Factor out the common theme variables again
asmeurer d5975ab
Fix the API name color with the latest version of Furo
asmeurer 6128f11
Fix some theme colors in dark mode
asmeurer 43bb6b4
Fix "parameters" and "returns" heading formatting for the latest vers…
asmeurer 38f71b4
Make the logo on the docs site higher resolution
asmeurer 2d225a5
Fix the code line spacing adjustment for the latest version of Furo
asmeurer 71a74b6
Fix various contrast issues in the dark mode docs
asmeurer a1158e6
Remove duplicate variable from conf.py
asmeurer f3722e4
Fix search icon color
asmeurer 0ce74d6
Fix some link colors
asmeurer 475380a
Clean up some CSS
asmeurer afed171
Fix some indentation
asmeurer 5867f1e
Make it so the whole sidebar in the docs scrolls
asmeurer ddf9dc2
Mark the current page in the sidebar using a background color
asmeurer 95cc3a1
Fix the link color CSS affecting the sidebar
asmeurer 90ff6b1
Add a version selector to the sidebar
asmeurer 5bfdbdf
Fix versions.json location
asmeurer 9248b53
Remove references to the SymPy Live documentation extension
asmeurer 7e23fab
Update the update_docs script for the new versions.json process
asmeurer cd67e45
Remove the generate_indexes.py command from Travis
asmeurer 538a4bd
Fix the color of the "Hide Search Matches" text
asmeurer d228e09
Fix the update_docs script
asmeurer 527aba6
Make the header text white
asmeurer a2064b3
Use better contrast colors for links
asmeurer d1bc958
Remove redundant CSS variable
asmeurer ca7a6a2
Remove the green underline on "SymPy documentation" on hover
asmeurer c233492
Remove unused layout.html template
asmeurer be278b9
Add html_basename to the docs
asmeurer abf5039
Use custom pygments styles with better color contrast in the docs
asmeurer a8e1e43
Fix some wording
asmeurer ed4c87d
Remove the pre line-height from custom.css
asmeurer 3439213
Remove an unnecessary piece of CSS
asmeurer 75c8be0
Fix the sidebar border color
asmeurer cb2182c
Make the API function names have better color contrast
asmeurer 29b0e08
Tone down the brand-primary color, and use it for the sidebar hover
asmeurer 83f918b
Clean up the dark theme colors
asmeurer 3ecf36c
Reapply the color-foreground-secondary for dark mode
asmeurer d7a3723
Fix the sidebar hover colors in dark mode
asmeurer 8bc4a04
Fix incorrect line wrapping in the CSS
asmeurer File filter
Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,3 +1,4 @@ | ||
furo | ||
linkify-it-py | ||
matplotlib | ||
matplotlib-inline | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,102 @@ | ||
""" | ||
Pygments styles used for syntax highlighting. | ||
|
||
These are based on the Sphinx style (see | ||
https://github.com/sphinx-doc/sphinx/blob/master/sphinx/pygments_styles.py) | ||
for light mode and the Friendly style for dark mode. | ||
|
||
The styles here have been adjusted so that they are WCAG AA compatible. The | ||
tool at https://github.com/mpchadwick/pygments-high-contrast-stylesheets was | ||
used to identify colors that should be adjusted. | ||
|
||
""" | ||
from pygments.style import Style | ||
from pygments.styles.friendly import FriendlyStyle | ||
from pygments.styles.native import NativeStyle | ||
from pygments.token import Comment, Generic, Literal, Name, Number, Text | ||
|
||
class SphinxHighContrastStyle(Style): | ||
""" | ||
Like Sphinx (which is like friendly, but a bit darker to enhance contrast | ||
on the green background) but with higher contrast colors. | ||
|
||
""" | ||
|
||
@property | ||
def _pre_style(self): | ||
# This is used instead of the default 125% so that multiline Unicode | ||
# pprint output looks good | ||
return 'line-height: 120%;' | ||
|
||
background_color = '#eeffcc' | ||
default_style = '' | ||
|
||
styles = FriendlyStyle.styles | ||
styles.update({ | ||
# These are part of the Sphinx modification to "friendly" | ||
Generic.Output: '#333', | ||
Number: '#208050', | ||
|
||
# These are adjusted from "friendly" (Comment is adjusted from | ||
# "sphinx") to have better color contrast against the background. | ||
Comment: 'italic #3c7a88', | ||
Comment.Hashbang: 'italic #3c7a88', | ||
Comment.Multiline: 'italic #3c7a88', | ||
Comment.PreprocFile: 'italic #3c7a88', | ||
Comment.Single: 'italic #3c7a88', | ||
Comment.Special: '#3a7784 bg:#fff0f0', | ||
Generic.Error: '#e60000', | ||
Generic.Inserted: '#008200', | ||
Generic.Prompt: 'bold #b75709', | ||
Name.Class: 'bold #0e7ba6', | ||
Name.Constant: '#2b79a1', | ||
Name.Entity: 'bold #c54629', | ||
Name.Namespace: 'bold #0e7ba6', | ||
Name.Variable: '#ab40cd', | ||
Text.Whitespace: '#707070', | ||
Literal.String.Interpol: 'italic #3973b7', | ||
Literal.String.Other: '#b75709', | ||
Name.Variable.Class: '#ab40cd', | ||
Name.Variable.Global: '#ab40cd', | ||
Name.Variable.Instance: '#ab40cd', | ||
Name.Variable.Magic: '#ab40cd', | ||
}) | ||
|
||
|
||
|
||
class NativeHighContrastStyle(NativeStyle): | ||
""" | ||
Like native, but with higher contrast colors. | ||
""" | ||
@property | ||
def _pre_style(self): | ||
# This is used instead of the default 125% so that multiline Unicode | ||
# pprint output looks good | ||
return 'line-height: 120%;' | ||
|
||
styles = NativeStyle.styles | ||
|
||
# These are adjusted to have better color contrast against the background | ||
styles.update({ | ||
Comment.Preproc: 'bold #e15a5a', | ||
Comment.Special: 'bold #f75050 bg:#520000', | ||
Generic.Deleted: '#e75959', | ||
Generic.Error: '#e75959', | ||
Generic.Traceback: '#e75959', | ||
Literal.Number: '#438dc4', | ||
Name.Builtin: '#2594a1', | ||
# We also remove the underline here from the original style | ||
Name.Class: '#548bd3', | ||
Name.Function: '#548bd3', | ||
# We also remove the underline here from the original style | ||
Name.Namespace: '#548bd3', | ||
Text.Whitespace: '#878787', | ||
Literal.Number.Bin: '#438dc4', | ||
Literal.Number.Float: '#438dc4', | ||
Literal.Number.Hex: '#438dc4', | ||
Literal.Number.Integer: '#438dc4', | ||
Literal.Number.Oct: '#438dc4', | ||
Name.Builtin.Pseudo: '#2594a1', | ||
Name.Function.Magic: '#548bd3', | ||
Literal.Number.Integer.Long: '#438dc4', | ||
}) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,108 @@ | ||
/* Completely disable blockquotes. The Furo defaults make block quotes very*/ | ||
/* apparent. However, the parameter blocks from numpydoc render as block | ||
* quotes, which looks bad. Furthermore, it is very easy for things to | ||
* accidentally have block quotes due to the fact that RST makes indented | ||
* blocks render as a block quote (unlike Markdown which makes indented blocks | ||
* render as code). There aren't any places in the documentation that use a | ||
* block quote on purpose. */ | ||
blockquote { | ||
border-left: inherit; | ||
font-style: inherit; | ||
margin-left: inherit; | ||
margin-right: inherit; | ||
padding: inherit; | ||
background-color: inherit; | ||
margin-block-start: -0.5rem; | ||
margin-block-end: -0.5rem; | ||
} | ||
|
||
/* Version selector. See _templates/sidebar/versions.html */ | ||
.versions-header { | ||
color: white; | ||
padding: var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal); | ||
margin: 1rem 0rem; | ||
} | ||
.current-version { | ||
background-color: #2f431e; | ||
} | ||
.versions-not-found { | ||
color: white; | ||
font-style: italic; | ||
padding: var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal); | ||
} | ||
|
||
/* Make the "SymPy documentation" text bold */ | ||
.sidebar-brand-text { | ||
font-weight: bold; | ||
} | ||
/* Remove the green underline from the "SymPy documentation" on hover */ | ||
.sidebar-brand:hover { | ||
text-decoration: none !important; | ||
} | ||
|
||
/* Make top-level items in the sidebar bold */ | ||
.sidebar-tree .toctree-l1>.reference, .sidebar-tree .toctree-l1>label .icon { | ||
font-weight: bold !important; | ||
} | ||
/* Indicate the current page using a background color rather than bold text */ | ||
.sidebar-tree .current-page>.reference { | ||
font-weight: normal; | ||
background-color: #2f431e; | ||
} | ||
/* Make sure the 'a' colors below don't affect the sidebar*/ | ||
.sidebar-tree .icon, .sidebar-tree .reference { | ||
color: var(--color-sidebar-link-text) !important; | ||
} | ||
|
||
/* The "hide search matches" text after doing a search. Defaults to the same | ||
color as the icon which is illegible on the green background. */ | ||
.highlight-link a { | ||
color: white !important; | ||
} | ||
|
||
.admonition.warning>.admonition-title { | ||
color: white; | ||
} | ||
|
||
/* Makes the text look better on Mac retina displays (the Furo CSS disables*/ | ||
/* subpixel antialiasing). */ | ||
body { | ||
-webkit-font-smoothing: auto; | ||
-moz-osx-font-smoothing: auto; | ||
} | ||
|
||
/* Disable upcasing of headers 4+ (they are still distinguishable by*/ | ||
/* font-weight and size) */ | ||
h4, h5, h6 { | ||
text-transform: inherit; | ||
} | ||
|
||
/* Make "Examples" and "Parameters" headers easier to see */ | ||
p.rubric, dl.c .field-list dt, dl.cpp .field-list dt, dl.js .field-list dt, dl.py .field-list dt, dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .field-list>dt { | ||
text-transform: none; | ||
font-weight: 600; | ||
font-size: 120%; | ||
} | ||
|
||
/* Disable underlines on links except on hover */ | ||
a { | ||
text-decoration: none; | ||
} | ||
a:hover { | ||
text-decoration: underline; | ||
} | ||
/* TODO: Some styling for visited? */ | ||
/* a:visited { */ | ||
/* color: #307748; */ | ||
/* text-decoration: none; */ | ||
/* } */ | ||
/* a:visited:hover { */ | ||
/* color: #307748; */ | ||
/* text-decoration: underline; */ | ||
/* } */ | ||
|
||
/* Disable the fancy scrolling behavior when jumping to headers (this is too | ||
slow for long pages) */ | ||
html { | ||
scroll-behavior: auto; | ||
} |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Well, this is your documentation, so do whateverr you want -- I'll note that I made blockquotes apparent because it was too easy to inject them by accident with reST, making them unusable when you actually want them. :)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I could make an effort to remove all the blockquotes, and maybe I should. This is a much easier thing for now. A big problem is that numpydoc is using blockquote for the parameters, which makes them look pretty bad. So we'd need to fix that (we're actually currently using a forked version of numpydoc, which could be part of the problem, but that just highlights the complexity). SymPy has a lot of documentation (over 270 RST files, most of which are pulling in documentation from docstrings). So any kind of content clean up like this would take a bit of effort, which is more than what I want to do for this PR.