diff --git a/docs/_static/custom.css b/docs/_static/custom.css index 9e733c1e9..2a00cd65e 100644 --- a/docs/_static/custom.css +++ b/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); -} diff --git a/docs/_static/logo-dark.svg b/docs/_static/logo-dark.svg new file mode 100644 index 000000000..56b4b4751 --- /dev/null +++ b/docs/_static/logo-dark.svg @@ -0,0 +1,12 @@ + + + + + + + + + + + + diff --git a/docs/_static/logo.svg b/docs/_static/logo.svg new file mode 100644 index 000000000..5d0ca25b8 --- /dev/null +++ b/docs/_static/logo.svg @@ -0,0 +1,12 @@ + + + + + + + + + + + + diff --git a/docs/_static/pandas-square.svg b/docs/_static/pandas-square.svg deleted file mode 100644 index f5ef20fc4..000000000 --- a/docs/_static/pandas-square.svg +++ /dev/null @@ -1,11 +0,0 @@ - - - - - - - - - - - diff --git a/docs/_static/pandas.svg b/docs/_static/pandas.svg deleted file mode 100644 index 017fd35fd..000000000 --- a/docs/_static/pandas.svg +++ /dev/null @@ -1 +0,0 @@ -Artboard 63 diff --git a/docs/_static/pydata-logo.png b/docs/_static/pydata-logo.png new file mode 100644 index 000000000..bfdf323b9 Binary files /dev/null and b/docs/_static/pydata-logo.png differ diff --git a/docs/conf.py b/docs/conf.py index 2dadf7171..5896d9bce 100644 --- a/docs/conf.py +++ b/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,10 +86,9 @@ "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", @@ -115,20 +96,24 @@ "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": { diff --git a/docs/index.rst b/docs/index.rst index 172b68d82..752151328 100644 --- a/docs/index.rst +++ b/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 `_ for initial design of the theme logo. .. toctree:: :caption: Theme Documentation diff --git a/docs/user_guide/configuring.rst b/docs/user_guide/configuring.rst index 074db0d4a..7e190c1f5 100644 --- a/docs/user_guide/configuring.rst +++ b/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": "" + "logo": { + "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:: diff --git a/docs/user_guide/customizing.rst b/docs/user_guide/customizing.rst index 18852cfaf..0e0eb4264 100644 --- a/docs/user_guide/customizing.rst +++ b/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. diff --git a/src/pydata_sphinx_theme/__init__.py b/src/pydata_sphinx_theme/__init__.py index 9db462c7e..82807ee13 100644 --- a/src/pydata_sphinx_theme/__init__.py +++ b/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 diff --git a/src/pydata_sphinx_theme/assets/styles/base/_base.scss b/src/pydata_sphinx_theme/assets/styles/base/_base.scss index 285dd1ffb..e07222b7e 100644 --- a/src/pydata_sphinx_theme/assets/styles/base/_base.scss +++ b/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; diff --git a/src/pydata_sphinx_theme/assets/styles/components/_icon-links.scss b/src/pydata_sphinx_theme/assets/styles/components/_icon-links.scss index 3bad838f3..28697a5a3 100644 --- a/src/pydata_sphinx_theme/assets/styles/components/_icon-links.scss +++ b/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 diff --git a/src/pydata_sphinx_theme/assets/styles/components/_switcher-version.scss b/src/pydata_sphinx_theme/assets/styles/components/_switcher-version.scss index 3189bf6a2..174f0ba04 100644 --- a/src/pydata_sphinx_theme/assets/styles/components/_switcher-version.scss +++ b/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); + } } diff --git a/src/pydata_sphinx_theme/assets/styles/components/_toc-inpage.scss b/src/pydata_sphinx_theme/assets/styles/components/_toc-inpage.scss index 845b91b8d..c0b999ed1 100644 --- a/src/pydata_sphinx_theme/assets/styles/components/_toc-inpage.scss +++ b/src/pydata_sphinx_theme/assets/styles/components/_toc-inpage.scss @@ -18,7 +18,7 @@ .toc-entry > .nav-link.active { font-weight: 600; - color: var(--pst-color-toc-link-active); + color: var(--pst-color-primary); background-color: transparent; - border-left: 2px solid var(--pst-color-toc-link-active); + border-left: 2px solid var(--pst-color-primary); } diff --git a/src/pydata_sphinx_theme/assets/styles/components/header/_header-logo.scss b/src/pydata_sphinx_theme/assets/styles/components/header/_header-logo.scss index 109dd1c1f..05420a3ca 100644 --- a/src/pydata_sphinx_theme/assets/styles/components/header/_header-logo.scss +++ b/src/pydata_sphinx_theme/assets/styles/components/header/_header-logo.scss @@ -5,6 +5,7 @@ padding: 0.5rem 0; display: flex; align-items: center; + gap: 0.5rem; // If there's no logo image, we use a p element w/ the site title p { diff --git a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss index 68d3d1bb8..5b5aa9bb9 100644 --- a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss +++ b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss @@ -7,10 +7,11 @@ html[data-theme="light"] { /***************************************************************************** * main colors */ - --pst-color-primary: rgb(19, 6, 84); + --pst-color-primary: rgb(69 157 185); + --pst-color-secondary: rgb(238 144 64); --pst-color-success: rgb(40, 167, 69); - --pst-color-info: rgb(0, 123, 255); - --pst-color-warning: rgb(255, 193, 7); + --pst-color-info: var(--pst-color-primary); + --pst-color-warning: var(--pst-color-secondary); --pst-color-danger: rgb(220, 53, 69); --pst-color-text-base: rgb(51, 51, 51); --pst-color-text-muted: rgb(77, 77, 77); @@ -41,8 +42,8 @@ html[data-theme="light"] { */ // links - --pst-color-link: rgb(0, 91, 129); - --pst-color-link-hover: rgb(227, 46, 0); + --pst-color-link: var(--pst-color-primary); + --pst-color-link-hover: var(--pst-color-secondary); // inline code --pst-color-inline-code: rgb(232, 62, 140); @@ -65,10 +66,11 @@ html[data-theme="dark"] { /***************************************************************************** * main colors */ - --pst-color-primary: rgb(76, 145, 219); + --pst-color-primary: rgb(69 157 185); + --pst-color-secondary: rgb(238 144 64); --pst-color-success: rgb(72, 135, 87); - --pst-color-info: rgb(64, 125, 191); - --pst-color-warning: rgb(193, 162, 69); + --pst-color-info: var(--pst-color-primary); + --pst-color-warning: var(--pst-color-secondary); --pst-color-danger: rgb(203, 70, 83); --pst-color-text-base: rgb(201, 209, 217); --pst-color-text-muted: rgb(192, 192, 192); @@ -100,7 +102,7 @@ html[data-theme="dark"] { // links --pst-color-link: var(--pst-color-primary); - --pst-color-link-hover: rgb(170, 103, 196); + --pst-color-link-hover: var(--pst-color-secondary); // inline code --pst-color-inline-code: rgb(221, 158, 194); diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-logo.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-logo.html index 3f459833a..f62e3f888 100644 --- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-logo.html +++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-logo.html @@ -1,18 +1,22 @@ -{% if not theme_logo_link %} +{% if not theme_logo.get("link") %} {% set href = pathto(root_doc) %} -{% elif theme_logo_link.startswith("http") %} - {% set href = theme_logo_link %} +{% elif theme_logo.get("link").startswith("http") %} + {# Logo link is to external URL} + {% set href = theme_logo.get("link") %} {% else %} - {% set href = pathto(theme_logo_link) %} + {# Logo link is to internal page #} + {% set href = pathto(theme_logo.get("link")) %} {% endif %} - - {% set is_logo = theme_dark_logo or theme_light_logo or logo %} + diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/version-switcher.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/version-switcher.html index 518e6ef12..83d386ff4 100644 --- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/version-switcher.html +++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/version-switcher.html @@ -1,5 +1,5 @@