Merge pull request #23159 from asmeurer/furo-restyling

Furo docs theme with styling

.travis.yml

@@ -118,7 +118,7 @@ script:
   - set -e
   - bin/test_travis.sh
   - if [[ "${TEST_SPHINX}" == "true" ]]; then
-    doctr deploy dev --deploy-repo sympy/sympy_doc --command './generate_indexes.py';
+    doctr deploy dev --deploy-repo sympy/sympy_doc
     fi
   - if [[ "${TEST_COVERAGE}" == "true" ]]; then
     bash <(curl -s https://codecov.io/bash) || echo "Codecov did not collect coverage reports";

doc/requirements.txt

@@ -1,3 +1,4 @@
+furo
 linkify-it-py
 matplotlib
 matplotlib-inline

doc/src/_pygments/styles.py

@@ -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',
+    })

doc/src/_static/custom.css

@@ -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;
+}