From ea3705a5abb6f027f035e0bb4ee4e428e12eb097 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Thu, 24 Feb 2022 14:32:58 -0800 Subject: [PATCH 1/6] Use dataclasses instead of extra_classes --- docs/_static/custom.css | 3 + docs/_static/switcher.json | 3 +- docs/conf.py | 5 ++ docs/user_guide/configuring.rst | 55 +++++++++++++++++-- .../_templates/version-switcher.html | 13 +++-- 5 files changed, 68 insertions(+), 11 deletions(-) create mode 100644 docs/_static/custom.css diff --git a/docs/_static/custom.css b/docs/_static/custom.css new file mode 100644 index 000000000..f8f726ddd --- /dev/null +++ b/docs/_static/custom.css @@ -0,0 +1,3 @@ +#version_switcher a[data-version-name*="stable"] { + background-color: #e2ffe2; +} diff --git a/docs/_static/switcher.json b/docs/_static/switcher.json index 7ecf5aab3..3944ff8a3 100644 --- a/docs/_static/switcher.json +++ b/docs/_static/switcher.json @@ -1,8 +1,7 @@ [ { "name": "dev", - "version": "latest", - "extra_classes": ["dev"] + "version": "latest" }, { "name": "0.8.0 (stable)", diff --git a/docs/conf.py b/docs/conf.py index 87ac521c2..d61b46ad1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -140,6 +140,7 @@ "demo/no-sidebar": [], # Test what page looks like with no sidebar items } +myst_heading_anchors = 2 html_context = { "github_user": "pandas-dev", @@ -156,3 +157,7 @@ # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ["_static"] + + +def setup(app): + app.add_css_file("custom.css") diff --git a/docs/user_guide/configuring.rst b/docs/user_guide/configuring.rst index d1f663387..278932267 100644 --- a/docs/user_guide/configuring.rst +++ b/docs/user_guide/configuring.rst @@ -386,9 +386,6 @@ each can have the following fields: switcher. - ``name``: an optional name to display in the switcher dropdown instead of the version string (e.g., "latest", "stable", "dev", etc). -- ``extra_classes``: an optional list of classes to add to the switcher - button for a given version (e.g., ``["dev", "rc"]``). These classes are only - added when the version is active. - ``url``: an optional URL. If provided, it links the version to ``url`` instead of ``switcher['url_template']``. @@ -403,7 +400,6 @@ Here is an example JSON file: }, { "version": "2.1rc1", - "extra_classes": ["dev", "rc"] }, { "version": "2.0" @@ -542,6 +538,57 @@ to insert a version switcher at the top of the left sidebar, while still keeping the default navigation below it. See :doc:`sections` for more information. +Style the switcher buttons +-------------------------- + +You may apply styles via CSS to any of the switcher buttons to control their look and feel. +Each button has two `HTML dataset entries `_ +that you can use to apply CSS rules to subsets of buttons. These entries are: + +.. code-block:: + + data-version + data-version-name + +For example, the link for an entry with ``version="0.2"``, +and ``name="My version"`` would have metadata like so: + +.. code-block:: html + + + +You can create CSS rules that select this metadata like so: + +.. code-block:: scss + + // Style all links with a specific subset of versions + #version_switcher a[data-version="0.2"], + #version_switcher a[data-version="0.3"] { + background-color: red; + } + // Style all links with `stable` in the version name + #version_switcher a[data-version-name*="stable"] { + background-color: green; + } + +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 red 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 red + #version_switcher_button[data-version-name*="dev"] { + background-color: green; + } + +.. seealso:: + + See the `MDN documentation on dataset properties `_ + for more information on using and styling with these properties. Add an Edit this Page button ============================ diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/_templates/version-switcher.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/_templates/version-switcher.html index ff6ee4544..d436319ac 100644 --- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/_templates/version-switcher.html +++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/_templates/version-switcher.html @@ -66,6 +66,11 @@ // trying to redirect, and if not, will redirect to the homepage // for that version of the docs. node.onclick = checkPageExistsAndRedirect; + // Add dataset values for the version and name in case people want + // to apply CSS styling based on this information. + node.dataset["versionName"] = entry.name; + node.dataset["version"] = entry.version; + $("#version_switcher_menu").append(node); // replace dropdown button text with the preferred display name of // this version, rather than using sphinx's {{ version }} variable. @@ -73,11 +78,9 @@ // version's entry if (entry.version == "{{ theme_switcher.get('version_match') }}") { node.classList.add("active"); - $("#version_switcher_button").text(entry.name); - // Add extra class to the button for the selected entry - if ("extra_classes" in entry) { - $("#version_switcher_menu").classList.add(...entry.extra_classes); - } + let btn = document.getElementById("version_switcher_button"); + btn.innerText = btn.dataset["activeVersionName"] = entry.name; + btn.dataset["activeVersion"] = entry.version; } }); }); From d59740678a1cdc34840f9a56cf3d83f506dc06ef Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Fri, 25 Feb 2022 12:49:21 -0800 Subject: [PATCH 2/6] Fix CSS --- docs/_static/custom.css | 5 +++++ docs/conf.py | 4 ++-- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/_static/custom.css b/docs/_static/custom.css index f8f726ddd..3c32e8421 100644 --- a/docs/_static/custom.css +++ b/docs/_static/custom.css @@ -1,3 +1,8 @@ #version_switcher a[data-version-name*="stable"] { background-color: #e2ffe2; } + +#version_switcher + a:not([data-version-name*="stable"]):not([data-version-name="dev"]) { + color: #ff8282; +} diff --git a/docs/conf.py b/docs/conf.py index d61b46ad1..6fd3d2783 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -124,8 +124,8 @@ # "left_sidebar_end": ["custom-template.html", "sidebar-ethical-ads.html"], # "footer_items": ["copyright", "sphinx-version", ""] "switcher": { - # "json_url": "/_static/switcher.json", - "json_url": "https://pydata-sphinx-theme.readthedocs.io/en/latest/_static/switcher.json", + "json_url": "/_static/switcher.json", + # "json_url": "https://pydata-sphinx-theme.readthedocs.io/en/latest/_static/switcher.json", "url_template": "https://pydata-sphinx-theme.readthedocs.io/en/{version}/", "version_match": version_match, }, From 5ba0c7adc3d57bac44e96ecd0f92e3757af81b22 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Fri, 25 Feb 2022 12:50:41 -0800 Subject: [PATCH 3/6] Uncomment proper json --- docs/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 6fd3d2783..d61b46ad1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -124,8 +124,8 @@ # "left_sidebar_end": ["custom-template.html", "sidebar-ethical-ads.html"], # "footer_items": ["copyright", "sphinx-version", ""] "switcher": { - "json_url": "/_static/switcher.json", - # "json_url": "https://pydata-sphinx-theme.readthedocs.io/en/latest/_static/switcher.json", + # "json_url": "/_static/switcher.json", + "json_url": "https://pydata-sphinx-theme.readthedocs.io/en/latest/_static/switcher.json", "url_template": "https://pydata-sphinx-theme.readthedocs.io/en/{version}/", "version_match": version_match, }, From 6f8e00d7ee4d39e2f68ecaf8aef160936508376c Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Fri, 25 Feb 2022 12:52:13 -0800 Subject: [PATCH 4/6] Fix docs' --- docs/user_guide/configuring.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user_guide/configuring.rst b/docs/user_guide/configuring.rst index 278932267..88bbde395 100644 --- a/docs/user_guide/configuring.rst +++ b/docs/user_guide/configuring.rst @@ -581,8 +581,8 @@ version, you could use the following CSS selector: .. code-block:: scss // If the active version has the name "dev", style it red - #version_switcher_button[data-version-name*="dev"] { - background-color: green; + #version_switcher_button[data-active-version-name*="dev"] { + background-color: red; } .. seealso:: From 11e9557bdce92baca1573fe14113d0b60069062a Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Sat, 5 Mar 2022 17:03:34 -0800 Subject: [PATCH 5/6] Fix up the CSS of the dropdown --- docs/_static/custom.css | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/_static/custom.css b/docs/_static/custom.css index 3c32e8421..6d43f224f 100644 --- a/docs/_static/custom.css +++ b/docs/_static/custom.css @@ -1,8 +1,16 @@ +/* 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"]) { - color: #ff8282; + 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); } From fab0c6668997462e9d31dedf7ddec42dd4521aaa Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Sat, 5 Mar 2022 17:05:22 -0800 Subject: [PATCH 6/6] Docs update --- docs/user_guide/configuring.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/user_guide/configuring.rst b/docs/user_guide/configuring.rst index 88bbde395..255ef447b 100644 --- a/docs/user_guide/configuring.rst +++ b/docs/user_guide/configuring.rst @@ -575,14 +575,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 red if it was a ``dev`` +For example, if you wanted to style the dropdown button orange 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 red + // If the active version has the name "dev", style it orange #version_switcher_button[data-active-version-name*="dev"] { - background-color: red; + background-color: rgb(255 138 62); } .. seealso::