Add logo and update brand colors (#698)

* Updates to logos and colors

* Minor tweaks

* primary color darker

* Admonitions

* Header links

* Version switcher colors

* Link

* Active color

* Color docs

* Favicon

* Fixing logo variables

* Logo dark

* Logo fixes

* Logo text fixes

* tests

* Diagonal logo

* Theme button more minimal

* No background

* Add single dictionary config for logo

* Deprecation

* fix stroke miters; optimize svg; fix stroke width on dark logo

Co-authored-by: Daniel McCloy <[email protected]>
Co-authored-by: Jarrod Millman <[email protected]>

docs/_static/custom.css

@@ -1,21 +1,9 @@
 :root {
   --sd-color-primary: var(--pst-color-primary);
+  --sd-color-secondary: var(--pst-color-secondary);
 }
 
 /* Background of stsable should be green */
 #version_switcher a[data-version-name*="stable"] {
   background-color: #e2ffe2;
 }
-
-/* Color of explicit versions should be orange */
-#version_switcher
-  a:not([data-version-name*="stable"]):not([data-version-name="dev"]) {
-  background-color: #f8f9fa;
-  color: grey;
-}
-
-/* If we're on a dev version, make the switcher button orange */
-#version_switcher_button[data-active-version-name*="dev"] {
-  background-color: rgb(255 138 62);
-  border-color: rgb(255 138 62);
-}

docs/conf.py

@@ -1,24 +1,9 @@
-# Configuration file for the Sphinx documentation builder.
-#
-# This file only contains a selection of the most common options. For a full
-# list see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
-
 # -- Path setup --------------------------------------------------------------
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
 import os
 
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
-
-
 # -- Project information -----------------------------------------------------
 
-project = "PyData Sphinx Theme"
+project = "PyData Theme"
 copyright = "2019, PyData Community"
 author = "PyData Community"
 
@@ -27,10 +12,6 @@
 
 # -- General configuration ---------------------------------------------------
 
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
-
 extensions = [
     "jupyter_sphinx",
     "myst_parser",
@@ -78,7 +59,8 @@
 # a list of builtin themes.
 #
 html_theme = "pydata_sphinx_theme"
-# html_logo = "_static/pandas.svg"  # For testing
+html_logo = "_static/logo.svg"
+html_favicon = "_static/logo.svg"
 
 # Define the json_url for our version switcher.
 json_url = "https://pydata-sphinx-theme.readthedocs.io/en/latest/_static/switcher.json"
@@ -104,31 +86,34 @@
             "url": "https://github.com/pydata/pydata-sphinx-theme/releases",
             "name": "Changelog",
         },
-        {"url": "https://pandas.pydata.org/pandas-docs/stable/", "name": "Pandas Docs"},
     ],
     "github_url": "https://github.com/pydata/pydata-sphinx-theme",
-    "twitter_url": "https://twitter.com/pandas_dev",
+    "twitter_url": "https://twitter.com/PyData",
     "icon_links": [
         {
             "name": "PyPI",
             "url": "https://pypi.org/project/pydata-sphinx-theme",
             "icon": "fas fa-box",
         },
         {
-            "name": "Pandas",
-            "url": "https://pandas.pydata.org",
-            "icon": "_static/pandas-square.svg",
+            "name": "PyData",
+            "url": "https://pydata.org",
+            "icon": "_static/pydata-logo.png",
             "type": "local",
         },
     ],
+    "logo": {
+        "text": "PyData Theme",
+        "image_dark": "logo-dark.svg",
+    },
     "use_edit_page_button": True,
     "show_toc_level": 1,
     # "show_nav_level": 2,
     # "search_bar_position": "navbar",  # TODO: Deprecated - remove in future version
     # "navbar_align": "left",  # [left, content, right] For testing that the navbar items align properly
-    # "navbar_start": ["navbar-logo", "navbar-version"],
+    "navbar_start": ["navbar-logo", "version-switcher"],
     # "navbar_center": ["navbar-nav", "navbar-version"],  # Just for testing
-    "navbar_end": ["theme-switcher", "version-switcher", "navbar-icon-links"],
+    "navbar_end": ["theme-switcher", "navbar-icon-links"],
     # "left_sidebar_end": ["custom-template.html", "sidebar-ethical-ads.html"],
     # "footer_items": ["copyright", "sphinx-version", ""]
     "switcher": {

docs/index.rst

@@ -45,6 +45,7 @@ To build this theme we drew inspiration from other great projects on the web tha
 - Docker: https://docs.docker.com/engine/docker-overview/
 - PyTorch: https://pytorch.org/docs/stable/notes/autograd.html
 
+Thanks to `@drammock <https://github.com/drammock>`_ for initial design of the theme logo.
 
 .. toctree::
    :caption: Theme Documentation

docs/user_guide/configuring.rst

@@ -31,19 +31,21 @@ Different logos for light and dark mode
 You may specify use a different version of your logo image for "light" and "dark" modes.
 This is useful if your logo image is not adapted to a dark mode (light background, not enough contrast, etc...).
 
-To do so, put the 2 image files in a folder that is in ``html_static_path`` and configure the relative path to each image with ``light_logo`` and ``dark_logo`` in ``html_theme_options``, like so:
+To do so, put the 2 image files in a folder that is in ``html_static_path`` and configure the relative path to each image with ``logo.image_light`` and ``logo.image_dark`` in ``html_theme_options``, like so:
 
 .. code-block:: python
 
    html_static_path = ["_static"]
    html_theme_options = {
-       "light_logo": "logo-light.png",
-       "dark_logo": "logo-dark.png",
+      "logo": {
+         "image_light": "logo-light.png",
+         "image_dark": "logo-dark.png",
+      }
    }
 
 .. note::
 
-   ``light_logo`` and ``dark_logo`` will override the ``html_logo`` setting. If you only specify one of them, but not the other, then the un-specified setting will re-use ``html_logo``.
+   ``image_light`` and ``image_dark`` will override the ``html_logo`` setting. If you only specify one of them, but not the other, then the un-specified setting will re-use ``html_logo``.
 
 Customize logo link
 -------------------
@@ -54,21 +56,27 @@ If you'd like it to link to another page or use an external link instead, use th
 .. code-block:: python
 
    html_theme_options = {
-       "logo_link": "<other page or external link>"
+       "logo": {
+           "link": "<other page or external link>",
+       }
    }
 
 Add a logo title
 ----------------
 
-To add a title in the brand section of your documentation, define a value for ``html_title``.
-This will appear just after your logo if it is set.
+To add a title in the brand section of your documentation, define a value for ``html_theme_options.logo["text"]``
+This will appear just after your logo image if it is set.
 
 .. code-block:: python
 
    html_theme_options = {
-       "html_title": "My awesome documentation"
+       "logo": {
+           "text": "My awesome documentation",
+       }
    }
 
+.. note:: The ``html_title`` field will work as well if no logo images are specified.
+
 
 .. _icon-links:
 
@@ -634,7 +642,7 @@ of the locations in ``html_theme_options`` (e.g., ``navbar_end``,
 
    html_theme_options = {
       ...,
-      "navbar_end": ["version-switcher"]
+      "navbar_start": ["navbar-logo", "version-switcher"]
    }
 
 
@@ -688,14 +696,14 @@ In addition, the parent button of the dropdown list contains similar metadata
 about the **current version**. This could be used to style the entire dropdown
 a certain color based on the active version.
 
-For example, if you wanted to style the dropdown button orange if it was a ``dev``
+For example, if you wanted to style the dropdown button to use the theme's secondary color (PyData orange by default) if it was a ``dev``
 version, you could use the following CSS selector:
 
 .. code-block:: scss
 
    // If the active version has the name "dev", style it orange
    #version_switcher_button[data-active-version-name*="dev"] {
-      background-color: rgb(255 138 62);
+      background-color: var(--pst-color-secondary);
    }
 
 .. seealso::

docs/user_guide/customizing.rst

@@ -189,6 +189,11 @@ For a complete list of the theme variables that you may override, see the
 Color variables
 ---------------
 
+There are two special color variables for primary and secondary theme colors (``--pst-color-primary`` and ``--pst-color-secondary``, respectively).
+These are meant to complement one another visually across the theme, if you modify these, choose colors that look good when paired with one another.
+
+There are also several other color variables that control color for admonitions, links, menu items, etc.
+
 Each color variable has two values, one corresponding to the "light" and one for the "dark" theme.
 These are used throughout many of the theme elements to define text color, background color, etc.
 

src/pydata_sphinx_theme/__init__.py

@@ -21,9 +21,9 @@
 
 
 def update_config(app, env):
-    theme_options = app.config["html_theme_options"]
+    theme_options = env.config.html_theme_options
 
-    # DEPRECATE after v0.9
+    # DEPRECATE >= v0.10
     if theme_options.get("search_bar_position") == "navbar":
         logger.warn(
             (
@@ -84,6 +84,34 @@ def update_config(app, env):
         app.add_js_file(None, body=gid_script)
 
 
+def prepare_html_config(app, pagename, templatename, context, doctree):
+    """Prepare some configuration values for the HTML build.
+
+    For some reason updating the html_theme_options in an earlier Sphinx
+    event doesn't seem to update the values in context, so we manually update
+    it here with our config.
+    """
+    # Prepare the logo config dictionary
+    theme_logo = context.get("theme_logo")
+    if not theme_logo:
+        # In case theme_logo is an empty string
+        theme_logo = {}
+    if not isinstance(theme_logo, dict):
+        raise ValueError(f"Incorrect logo config type: {type(theme_logo)}")
+
+    # DEPRECATE: >= 0.11
+    if context.get("theme_logo_link"):
+        logger.warn(
+            (
+                "DEPRECATION: Config `logo_link` will be deprecated in v0.11. "
+                "Use the `logo.link` configuration dictionary instead."
+            )
+        )
+        theme_logo = context.get("theme_logo_link")
+
+    context["theme_logo"] = theme_logo
+
+
 def update_templates(app, pagename, templatename, context, doctree):
     """Update template names and assets for page build."""
     # Allow for more flexibility in template names
@@ -664,6 +692,7 @@ def setup(app):
     app.connect("html-page-context", setup_edit_url)
     app.connect("html-page-context", add_toctree_functions)
     app.connect("html-page-context", update_templates)
+    app.connect("html-page-context", prepare_html_config)
     app.connect("build-finished", _overwrite_pygments_css)
 
     # Include component templates

src/pydata_sphinx_theme/assets/styles/base/_base.scss

@@ -48,7 +48,7 @@ a {
   }
 
   &.headerlink {
-    color: var(--pst-color-danger);
+    color: var(--pst-color-warning);
     opacity: 0.4;
     font-size: 0.8em;
     padding: 0 4px 0 4px;

src/pydata_sphinx_theme/assets/styles/components/_icon-links.scss

@@ -30,6 +30,7 @@
 
   img.icon-link-image {
     height: 1.5em;
+    border-radius: 0.2rem;
   }
 
   // inline the element in the navbar as long as they fit and use display block when colapsing

src/pydata_sphinx_theme/assets/styles/components/_switcher-version.scss

@@ -1,4 +1,12 @@
 #version_switcher_button {
-  background-color: var(--pst-color-primary);
-  border-color: var(--pst-color-primary);
+  border-color: var(--pst-color-border);
+  color: var(--pst-color-text-base);
+}
+
+#version_switcher_menu {
+  // Over-rides Bootstrap default blue
+  a.list-group-item.active {
+    background-color: var(--pst-color-primary);
+    border-color: var(--pst-color-primary);
+  }
 }