diff --git a/docs/_static/switcher.json b/docs/_static/switcher.json index a1c4edd6c..c1406d725 100644 --- a/docs/_static/switcher.json +++ b/docs/_static/switcher.json @@ -1,4 +1,7 @@ -[ +{ + "preferred_version": "stable", + "development_version": "latest", + "entries": [ { "name": "dev", "version": "latest", @@ -54,4 +57,5 @@ "version": "v0.3.2", "url": "https://pydata-sphinx-theme.readthedocs.io/en/v0.3.2/" } -] +], +} diff --git a/docs/user_guide/version-dropdown.rst b/docs/user_guide/version-dropdown.rst index 2973a0241..d6c135b05 100644 --- a/docs/user_guide/version-dropdown.rst +++ b/docs/user_guide/version-dropdown.rst @@ -31,9 +31,14 @@ Below is a more in-depth description of each of these configuration steps. Add a JSON file to define your switcher's versions -------------------------------------------------- -First, write a JSON file stating which versions of your docs will be listed in -the switcher's dropdown menu. That file should contain a list of entries that -each can have the following fields: +First, create a JSON file stating which versions of your docs will be listed in +the switcher's dropdown menu. +The contents of this file are a **dictionary** of key-val pairs that configure the version switcher. + +The only required key of this configuration is called ``entries``. +It corresponds to a list of entries for each version of the documentation you wish to include. + +Each item in ``entries`` may have the following fields: - ``version``: a version string. This is checked against ``switcher['version_match']`` to provide styling to the switcher. @@ -41,33 +46,37 @@ each can have the following fields: - ``name``: an optional name to display in the switcher dropdown instead of the version string (e.g., "latest", "stable", "dev", etc). -Here is an example JSON file: - -.. code:: json - - [ - { - "name": "v2.1 (stable)", - "version": "2.1", - "url": "https://mysite.org/en/2.1/index.html" - }, - { - "version": "2.1rc1", - "url": "https://mysite.org/en/2.1rc1/index.html" - }, - { - "version": "2.0", - "url": "https://mysite.org/en/2.0/index.html" - }, - { - "version": "1.0", - "url": "https://mysite.org/en/1.0/index.html" - } - ] +Here is an example JSON file that adds a list of several version entries. + +.. code-block:: json + :caption: switcher.json + + { + "entries":[ + { + "name":"v2.1 (stable)", + "version":"2.1", + "url":"https://mysite.org/en/2.1/index.html" + }, + { + "version":"2.2rc1", + "url":"https://mysite.org/en/2.2rc1/index.html" + }, + { + "version":"2.0", + "url":"https://mysite.org/en/2.0/index.html" + }, + { + "version":"1.0", + "url":"https://mysite.org/en/1.0/index.html" + } + ] + } -See the discussion of ``switcher['json_url']`` (below) for options of where to -save the JSON file. +In addition to ``entries`` there are a few other key/value configuration options, as explained below. +See :ref:`switcher-url-location` for options of where to save the JSON file. +.. _switcher-url-location: Configure ``switcher['json_url']`` ---------------------------------- @@ -222,3 +231,76 @@ version, you could use the following CSS selector: See the `MDN documentation on dataset properties `_ for more information on using and styling with these properties. + + +Add a warning banner to direct users to a specific version +---------------------------------------------------------- + +You can add a large warning banner to direct users to a specific version of your documentation if they are on a different version. +This is useful if you have many versions of your documentation (e.g. old releases, development versions) and wish to direct users to a specific version (e.g., the latest stable version). + +To activate this feature, use the ``preferred_version`` key in your ``versions.json`` configuration file. +The value should be the unique identifier of the version to which users should be redirected. + +For example, below we modify the ``switcher.json`` file described above to note version ``2.1`` as the preferred version. + +.. code-block:: json + :caption: switcher.json + + { + "preferred_version":"2.1", + "entries":[ + { + "name":"v2.1 (stable)", + "version":"2.1", + "url":"https://mysite.org/en/2.1/index.html" + }, + { + "version":"2.2rc1", + "url":"https://mysite.org/en/2.2rc1/index.html" + }, + { + "version":"2.0", + "url":"https://mysite.org/en/2.0/index.html" + }, + { + "version":"1.0", + "url":"https://mysite.org/en/1.0/index.html" + } + ], + } + +For all documentation pages on a different version, a large warning banner will be displayed stating that they they are on an out-of-date version, with a button to direct them to the preferred version. + +Specify that an outdated version is a *development* version +``````````````````````````````````````````````````````````` + +If a version is a "development" version instead of an out-dated version, you may change the message that is displayed. +To do so, add a ``development_version`` key to your JSON configuration, like so: + +.. code-block:: json + :caption: switcher.json + + { + "preferred_version":"2.1", + "development_version":"2.2rc1", + "entries":[ + { + "name":"v2.1 (stable)", + "version":"2.2rc1", + "url":"https://mysite.org/en/2.1/index.html" + }, + { + "version":"2.2rc1", + "url":"https://mysite.org/en/2.2rc1/index.html" + }, + { + "version":"2.0", + "url":"https://mysite.org/en/2.0/index.html" + }, + { + "version":"1.0", + "url":"https://mysite.org/en/1.0/index.html" + } + ], + } \ No newline at end of file diff --git a/src/pydata_sphinx_theme/__init__.py b/src/pydata_sphinx_theme/__init__.py index 48220d231..3be7d4303 100644 --- a/src/pydata_sphinx_theme/__init__.py +++ b/src/pydata_sphinx_theme/__init__.py @@ -18,7 +18,7 @@ from .bootstrap_html_translator import BootstrapHTML5Translator -__version__ = "0.10.1" +__version__ = "0.10.1dev0" logger = logging.getLogger(__name__) diff --git a/src/pydata_sphinx_theme/assets/scripts/index.js b/src/pydata_sphinx_theme/assets/scripts/index.js index d2817fcb5..e921bb49b 100644 --- a/src/pydata_sphinx_theme/assets/scripts/index.js +++ b/src/pydata_sphinx_theme/assets/scripts/index.js @@ -303,8 +303,15 @@ if (themeSwitchBtns) { btn.dataset["activeVersionName"] = ""; btn.dataset["activeVersion"] = ""; }); + + // If data is a list, turn it into a dictionary with an `entries` field + if (data.isArray()) { + data = {"entries": data}; + console.log("[PST]: Version switcher entries were a list. Moving to `entries` key.") + } + // create links to the corresponding page in the other docs versions - $.each(data, function (index, entry) { + $.each(data["entries"], function (index, entry) { // if no custom name specified (e.g., "latest"), use version string if (!("name" in entry)) { entry.name = entry.version; @@ -345,7 +352,35 @@ if (themeSwitchBtns) { btn.dataset["activeVersion"] = entry.version; }); } + + // If a preferred_version is specified and it is this entry, store the + // entry's information to use later. + if (entry.version === data["preferred_version"]) { + var preferred_version = entry.version; + } }); + + // If this is a preferred version, display a banner to redirect to it. + if ((preferred_version) && (preferred_version != btn.dataset["activeVersion"])) { + // Specify whether we are on an old version or a development version + if ((data["development_version"]) && (data["development_version"] == btn.dataset["activeVersion"])) { + var redirect_msg = "This a development version of the documentation." + } else { + var redirect_msg = "This is an outdated version of the documentation." + }; + + // Replace our warning banner placeholder with a visible banner + placeholder = document.getElementById("header-version-warning-placeholder"); + placeholder.insertAdjacentHTML("afterend", ` +
+
+ ${redirect_msg} + +
+
+ `); + console.log("[PST]: Inserted version warning banner..."); + } } ); } diff --git a/src/pydata_sphinx_theme/assets/styles/index.scss b/src/pydata_sphinx_theme/assets/styles/index.scss index 6130ecc51..468f431c0 100644 --- a/src/pydata_sphinx_theme/assets/styles/index.scss +++ b/src/pydata_sphinx_theme/assets/styles/index.scss @@ -40,6 +40,7 @@ $grid-breakpoints: ( @import "./sections/footer-article"; @import "./sections/header"; @import "./sections/header-article"; +@import "./sections/header-version-warning"; @import "./sections/sidebar-primary"; @import "./sections/sidebar-secondary"; @import "./sections/sidebar-toggle"; diff --git a/src/pydata_sphinx_theme/assets/styles/sections/header-version-warning.scss b/src/pydata_sphinx_theme/assets/styles/sections/header-version-warning.scss new file mode 100644 index 000000000..2e9c52ea9 --- /dev/null +++ b/src/pydata_sphinx_theme/assets/styles/sections/header-version-warning.scss @@ -0,0 +1,34 @@ +/** + * A warning banner to direct users to a stable version of the documentation. + */ + .bd-header-version-warning { + position: relative; // So the background color variable fill works + padding: 1rem; + + .bd-header-version-warning__content { + @include background-from-color-variable(--pst-color-danger, 0.2); + display: flex; + justify-content: center; + align-content: center; + gap: 1rem; + font-size: 1.2rem; + + span { + margin: auto 0; + text-align: center; + } + + // The button to the right of the banner text. + a { + z-index: 1; // To put it above the background banner. + button { + font-size: 1.2rem; + background-color: var(--pst-color-danger); + color: var(--pst-color-on-background); + &:active { + opacity: 0.8; + } + } + } + } +} \ No newline at end of file diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html index 60ff5e48c..6c9062a02 100644 --- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html +++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html @@ -78,6 +78,10 @@ {% endblock %} + {# Versoin warning placeholder that is replaced by the switcher JS #} + {% include "sections/version-warning.html" %} + + {# Main container for site content sections #}
{# Primary sidebar #} diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/version-warning.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/version-warning.html new file mode 100644 index 000000000..d90aecb21 --- /dev/null +++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/version-warning.html @@ -0,0 +1,6 @@ +{# A placeholder for a version warning that will be replaced with a banner #} +{# ref: components/version-switcher.html for JS that does this #} +{%- if theme_switcher %} + +
+{% endif -%}