diff --git a/docs/_static/custom.css b/docs/_static/custom.css new file mode 100644 index 000000000..6d43f224f --- /dev/null +++ b/docs/_static/custom.css @@ -0,0 +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"]) { + 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); +} 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 8b46b1894..2627d0a6a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -145,6 +145,7 @@ "demo/no-sidebar": [], # Test what page looks like with no sidebar items } +myst_heading_anchors = 2 html_context = { "github_user": "pandas-dev", @@ -161,3 +162,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..255ef447b 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 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 orange + #version_switcher_button[data-active-version-name*="dev"] { + background-color: rgb(255 138 62); + } + +.. 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 9fcd27b10..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")[0].classList.add(...entry.extra_classes); - } + let btn = document.getElementById("version_switcher_button"); + btn.innerText = btn.dataset["activeVersionName"] = entry.name; + btn.dataset["activeVersion"] = entry.version; } }); });