Use native font stack / remove vendored open-sans + lato fonts (#285)

Co-authored-by: Nicholas Bollweg <[email protected]>

Author: jorisvandenbossche

docs/contributing.rst

@@ -215,31 +215,44 @@ Then run the tests by calling ``pytest`` from the repository root.
 Changing fonts
 --------------
 
-Fonts are an important, performance-sensitive, but ultimately, subjective, part
-of the theme. The current font selections are:
+Three "styles" of the `FontAwesome 5 Free <https://fontawesome.com/icons?m=free>`__
+icon font are used for :ref:`icon links <icon-links>` and admonitions, and is
+the only `vendored` font. Further font choices are described in the :ref:`customizing`
+section of the user guide, and require some knowledge of HTML and CSS.
 
-- managed as dependencies in ``package.json``
+.. Attention::
+
+    Previously-included fonts like `Lato` have been removed, preferring
+    the most common default system fonts of the reader's computer. This provides
+    both better performance, and better script/glyph coverage than custom fonts,
+    and is recommended in most cases.
+
+The remaining vendored font selection is:
+
+- managed as a dependency in ``package.json``
 
-  - allowing the versions to be managed centrally
+  - allowing the version to be managed centrally
 
 - copied directly into the site statics, including licenses
 
-  - allowing the chosen fonts to be replaced (or removed entirely) with minimal
-    templating changes
+  - allowing the chosen font to be replaced (or removed entirely) with minimal
+    templating changes: practically, changing the icon font is difficult at this
+    point.
 
-- partially preloaded (mostly icons)
+- partially preloaded
 
-  - reducing flicker and re-layout artifacts
+  - reducing flicker and re-layout artifacts of early icon renders
 
 - mostly managed in ``webpack.common.js``
 
-  - allowing upgrades to be handled in a relatively sane, manageable way
+  - allowing upgrades to be handled in a relatively sane, manageable way, to
+    ensure the most recent icons
 
 
 Upgrading a font
 ^^^^^^^^^^^^^^^^
 
-If *only* the version of an `existing` font must change, for example to enable
+If *only* the version of the `existing` font must change, for example to enable
 new icons, run:
 
 .. code-block:: bash
@@ -255,21 +268,21 @@ Changing a font
 ^^^^^^^^^^^^^^^
 
 If the above doesn't work, for example if file names for an existing font change,
-or a new font altogether is being added, hand-editing of ``webpack.common.js`` is
-required. The steps are roughly:
+or a new font variant altogether is being added, hand-editing of ``webpack.common.js``
+is required. The steps are roughly:
 
 - install the new font, as above, with ``yarn add``
 - in ``webpack.common.js``:
 
   - add the new font to ``vendorVersions`` and ``vendorPaths``
   - add new ``link`` tags to the appropriate macro in ``macroTemplate``
   - add the new font files (including the license) to ``CopyPlugin``
-  - remove referencs to the font being replaced/removed, if applicable
+  - remove references to the font being replaced/removed, if applicable
 
 - restart the development server, if running
 - rebuild the production assets, as above, with ``yarn build:production``
 - potentially remove the font being replaced from ``package.json`` and re-run ``yarn``
-- commit all of the changes files
+- commit all of the changed files
 
 
 Contributing changes

docs/user_guide/configuring.rst

@@ -29,6 +29,8 @@ If you'd like it to link to another page or use an external link instead, use th
    }
 
 
+.. _icon-links:
+
 Configure icon links
 ====================
 

docs/user_guide/customizing.rst

@@ -30,6 +30,8 @@ To add a custom stylesheet, follow these steps:
 
 When you build your documentation, this stylesheet should now be activated.
 
+.. _css-variables:
+
 CSS Theme variables
 ===================
 
@@ -49,7 +51,7 @@ In order to change a variable, follow these steps:
    .. code-block:: none
 
        :root {
-           --font-size-base: 17px;
+           --pst-font-size-base: 17px;
        }
 
 For a complete list of the theme variables that you may override, see the
@@ -65,37 +67,60 @@ For a complete list of the theme variables that you may override, see the
 Replacing/Removing Fonts
 ========================
 
-The theme contains custom web fonts, in several formats, for different purposes:
+The theme includes the `FontAwesome 5 Free <https://fontawesome.com/icons?m=free>`__
+icon font (the ``.fa, .far, .fas`` styles, which are used for
+:ref:`icon links <icon-links>` and admonitions). 
+This is the only `vendored` font, and otherwise the theme by default relies on
+available system fonts for normal body text and headers.
+
+.. Attention::
+
+    Previously-included fonts like `Lato` have been removed, preferring
+    the most common default system fonts of the reader's computer. This provides
+    both better performance, and better script/glyph coverage than custom fonts,
+    and is recommended in most cases.
+
+The default body and header fonts can be changed as follows:
+
+- Using :ref:`custom-css`, you can specify which fonts to use for body, header
+  and monospace text. For example, the following can be added to a custom
+  css file:
 
-- "normal" body text, on ``body``
-- page and section headers, on ``.header-style``
-- icons, on ``.fa, .far, .fas``
+  .. code-block:: none
 
-While altering the icon font is presently somewhat involved, the body and header fonts,
-often paired together, can be replaced (or removed altogether) by:
+      :root {
+          --pst-font-family-base: Verdana, var(--pst-font-family-base-system);
+          --pst-font-family-heading: Cambria, Georgia, Times, var(--pst-font-family-base-system);
+          --pst-font-family-monospace: Courier, var(--pst-font-family-monospace-system);
+      }
 
-- configuring `template_path <https://www.sphinx-doc.org/en/master/theming.html#templating>`__
-  in your ``conf.py``
-- creating a custom ``layout.html`` Jinja2 template which overloads the ``fonts`` block
+  The ``-system`` variables are available to use as fallback to the default fonts.
 
-.. code-block:: html+jinja
+- If the font you want to specify in the section above is not generally available
+  by default, you will additionally need to ensure the font is loaded.
+  For example, you could download and vendor the font in the ``_static`` directory
+  of your Sphinx site, and then update the base template to load the font resources:
 
-    {% extends "pydata_sphinx_theme/layout.html" %}
+  - Configure the `template_path <https://www.sphinx-doc.org/en/master/theming.html#templating>`__
+    in your ``conf.py``
+  - Create a custom ``layout.html`` Jinja2 template which overloads the ``fonts`` block
+    (example for loading the Lato font that is included in the ``_static/vendor`` directory):
 
-    {% block fonts %}
+    .. code-block:: html+jinja
+
+      {% extends "pydata_sphinx_theme/layout.html" %}
+
+      {% block fonts %}
         <!-- add `style` or `link` tags with your CSS `@font-face` declarations here -->
-        <!-- ... and a `style` tag with setting `font-family` in `body` and `.header-style` -->
         <!-- ... and optionally preload the `woff2` for snappier page loads -->
-        <!-- or add a `style` tag with a font fallback chain with good cross-platform coverage -->
-        <style>
-            body {
-                font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Open Sans', 'Helvetica Neue', sans-serif;
-            }
-            .header-style {
-                font-family: Cambria, Cochin, Georgia, Times, 'Times New Roman', serif;
-            }
-        </style>
-    {% endblock %}
+        <link rel="stylesheet" href="{{ pathto('_static/vendor/lato_latin-ext/1.44.1/index.css', 1) }}">
+
+      {% endblock %}
+
+    To reduce the `Flash of Unstyled Content`, you may wish to explore various options for
+    `preloading content <https://developer.mozilla.org/en-US/docs/Web/HTML/Preloading_content>`__,
+    specifically the binary font files. This ensure the files will be loaded
+    before waiting for the CSS to be parsed, but should be used with care.
 
 .. _pydata-css-variables: https://github.com/pydata/pydata-sphinx-theme/blob/master/pydata_sphinx_theme/static/css/theme.css
 .. _css-variable-help: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties 

package.json

@@ -31,8 +31,6 @@
   },
   "dependencies": {
     "@fortawesome/fontawesome-free": "^5.13.0",
-    "@openfonts/lato_latin-ext": "^1.44.1",
-    "@openfonts/open-sans_all": "^1.44.1",
     "bootstrap": "^4.4.1",
     "jquery": "3.5.1",
     "optimize-css-assets-webpack-plugin": "^5.0.3",

pydata_sphinx_theme/static/css/index.57d3cd9fdfd1e83932aa4eb4774f9fb9.css renamed to pydata_sphinx_theme/static/css/index.101715efdecc9b59cb6e1ddfa685c31f.css

@@ -23,8 +23,15 @@
   /*****************************************************************************
   * Font family
   **/
-  --pst-font-family-base: 'Lato', sans-serif;
-  --pst-font-family-heading: 'Open Sans', sans-serif;
+  /* These are adapted from https://systemfontstack.com/ */
+  --pst-font-family-base-system: -apple-system, BlinkMacSystemFont, Segoe UI, "Helvetica Neue",
+    Arial, sans-serif, Apple Color Emoji, Segoe UI Emoji, Segoe UI Symbol;
+  --pst-font-family-monospace-system: "SFMono-Regular", Menlo, Consolas, Monaco,
+    Liberation Mono, Lucida Console, monospace;
+
+  --pst-font-family-base: var(--pst-font-family-base-system);
+  --pst-font-family-heading: var(--pst-font-family-base);
+  --pst-font-family-monospace: var(--pst-font-family-monospace-system);
 
   /*****************************************************************************
   * Color