From fd6dd523f9b8c24914bcd7069d88012a272a9ef0 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Fri, 1 Jul 2022 16:58:40 +0200 Subject: [PATCH 1/5] NEW: Add version warning banners --- docs/conf.py | 1 + docs/user_guide/configuring.rst | 23 +++++++++++++ .../assets/styles/index.scss | 2 ++ .../sections/_header-version-warning.scss | 34 +++++++++++++++++++ .../components/version-switcher.html | 26 +++++++++++++- .../theme/pydata_sphinx_theme/layout.html | 1 + .../sections/version-warning.html | 5 +++ 7 files changed, 91 insertions(+), 1 deletion(-) create mode 100644 src/pydata_sphinx_theme/assets/styles/sections/_header-version-warning.scss create mode 100644 src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/version-warning.html diff --git a/docs/conf.py b/docs/conf.py index 65b7d47ab..0fbd9ecf9 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -137,6 +137,7 @@ "switcher": { "json_url": json_url, "version_match": version_match, + "direct_to_version": "stable", }, } diff --git a/docs/user_guide/configuring.rst b/docs/user_guide/configuring.rst index ec88863d7..d52a1a5fc 100644 --- a/docs/user_guide/configuring.rst +++ b/docs/user_guide/configuring.rst @@ -696,6 +696,29 @@ for more information). Example: } +Add a warning banner for outdated versions +------------------------------------------ + +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, add the ``direct_to_version`` key in your ``switcher`` configuration. +For example: + +.. code-block:: python + + version = my_package_name.__version__.replace("dev0", "") # may differ + html_theme_options = { + ..., + "switcher": { + "version_match": version, + # If version of this documentation is not `stable` (in switcher.json), + # display a banner directing to `stable` + "direct_to_version": "stable", + } + } + + Specify where to display the switcher ------------------------------------- diff --git a/src/pydata_sphinx_theme/assets/styles/index.scss b/src/pydata_sphinx_theme/assets/styles/index.scss index 80ef64799..8c937df1c 100644 --- a/src/pydata_sphinx_theme/assets/styles/index.scss +++ b/src/pydata_sphinx_theme/assets/styles/index.scss @@ -39,6 +39,8 @@ $grid-breakpoints: ( @import "./sections/footer"; @import "./sections/footer-article"; @import "./sections/header"; +@import "./sections/header-version-warning"; + @import "./sections/sidebar-primary"; @import "./sections/sidebar-secondary"; 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..87559d726 --- /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; + } + } + } + } +} 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 78aa9e145..764d73643 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 @@ -43,6 +43,12 @@ // Set empty strings by default so that these attributes exist and can be used in CSS selectors btn.dataset["activeVersionName"] = ""; btn.dataset["activeVersion"] = ""; + + // The version of the current documentation page + let currentVersion = "{{ theme_switcher.get('version_match') }}"; + // A version we'll direct users to via a banner if different from current version + let directToVersion = "{{ theme_switcher.get('direct_to_version') }}"; + // create links to the corresponding page in the other docs versions $.each(data, function(index, entry) { // if no custom name specified (e.g., "latest"), use version string @@ -72,12 +78,30 @@ // this version, rather than using sphinx's {{ version }} variable. // also highlight the dropdown entry for the currently-viewed // version's entry - if (entry.version == "{{ theme_switcher.get('version_match') }}") { + if (entry.version == currentVersion) { node.classList.add("active"); btn.innerText = btn.dataset["activeVersionName"] = entry.name; btn.dataset["activeVersion"] = entry.version; } + + // If this entry is the one we wish to direct to + // And this entry is not currently active + // then add a banner to direct people there + if ((entry.version == directToVersion) && (directToVersion != currentVersion)) { + placeholder = document.getElementById("header-version-warning-placeholder"); + placeholder.insertAdjacentHTML("afterend", ` +
+
+ This documentation is for an unreleased or outdated version. + +
+
+ `); + console.log("[PST]: Inserted version warning banner..."); + } + }); + }); })(); 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 b8907b4be..b3da8fb03 100644 --- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html +++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html @@ -32,6 +32,7 @@ {%- include "sections/header.html" %} {% endblock %} + {% include "sections/version-warning.html" %}
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..54882926b --- /dev/null +++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/version-warning.html @@ -0,0 +1,5 @@ +{# 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.get('direct_to_version') %} +
+{% endif -%} From 121005789cfb9b25ecee67149ba527a7cc0798ec Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Fri, 1 Jul 2022 17:08:14 +0200 Subject: [PATCH 2/5] File path --- .../theme/pydata_sphinx_theme/components/version-switcher.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 764d73643..538f55cb3 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 @@ -93,7 +93,7 @@
This documentation is for an unreleased or outdated version. - +
`); From b8846a094a1671fbf00a2b36c4a1fd2c5580e216 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Fri, 1 Jul 2022 17:15:57 +0200 Subject: [PATCH 3/5] Tests --- .../theme/pydata_sphinx_theme/sections/version-warning.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 54882926b..dc29d79ae 100644 --- 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 @@ -1,5 +1,5 @@ {# 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.get('direct_to_version') %} +{%- if theme_switcher and theme_switcher.get('direct_to_version') %}
{% endif -%} From 2039619578e7d29d326a2c3ed8006de2de4c962f Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Fri, 1 Jul 2022 22:44:25 +0200 Subject: [PATCH 4/5] Using switcher.json only for banner redirect --- docs/_static/switcher.json | 2 + docs/conf.py | 1 - docs/user_guide/configuring.rst | 50 ++++++++++++++----- .../components/version-switcher.html | 17 +++++-- .../sections/version-warning.html | 3 +- 5 files changed, 53 insertions(+), 20 deletions(-) diff --git a/docs/_static/switcher.json b/docs/_static/switcher.json index c6a4c5606..33f5fd23b 100644 --- a/docs/_static/switcher.json +++ b/docs/_static/switcher.json @@ -2,11 +2,13 @@ { "name": "dev", "version": "latest", + "type": "development", "url": "https://pydata-sphinx-theme.readthedocs.io/en/latest/" }, { "name": "0.9.0 (stable)", "version": "stable", + "preferred": "true", "url": "https://pydata-sphinx-theme.readthedocs.io/en/stable/" }, { diff --git a/docs/conf.py b/docs/conf.py index 0fbd9ecf9..65b7d47ab 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -137,7 +137,6 @@ "switcher": { "json_url": json_url, "version_match": version_match, - "direct_to_version": "stable", }, } diff --git a/docs/user_guide/configuring.rst b/docs/user_guide/configuring.rst index d52a1a5fc..515a387c5 100644 --- a/docs/user_guide/configuring.rst +++ b/docs/user_guide/configuring.rst @@ -702,22 +702,46 @@ Add a warning banner for outdated versions 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, add the ``direct_to_version`` key in your ``switcher`` configuration. -For example: +To activate this feature, add ``"preferred": "true"`` to one of the entries in your ``switcher.json`` file. +This will mark it as the "preferred version" that other versions should direct to. -.. code-block:: python +In addition, you may mark some versions with a ``"type"`` which will slightly modify the banner message displayed. +To do so, add ``"type": "development"`` to any entry with one of three options, described below. - version = my_package_name.__version__.replace("dev0", "") # may differ - html_theme_options = { - ..., - "switcher": { - "version_match": version, - # If version of this documentation is not `stable` (in switcher.json), - # display a banner directing to `stable` - "direct_to_version": "stable", - } - } +- ``"type": "release"`` (default if no type specified): a **previous release**. +- ``"type": "releasecandidate"``: a **release candidate**. +- ``"type": "development"``: a **development branch**. + +For example, below we demonstrate a ``switcher.json`` with five entries: a development version, the latest release (which is preferred), a release candidate, and two previous releases. + +.. code:: json + [ + { + "name": "v2.2dev0 (development)", + "version": "v2.2dev0", + "type": "development", + "url": "https://mysite.org/en/2.1/index.html" + }, { + "name": "v2.1 (stable)", + "version": "2.1", + "preferred": "true", + "url": "https://mysite.org/en/2.1/index.html" + }, + { + "version": "2.1rc1", + "type": "releasecandidate", + "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" + } + ] Specify where to display the switcher ------------------------------------- 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 538f55cb3..8200c2451 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 @@ -46,8 +46,9 @@ // The version of the current documentation page let currentVersion = "{{ theme_switcher.get('version_match') }}"; - // A version we'll direct users to via a banner if different from current version - let directToVersion = "{{ theme_switcher.get('direct_to_version') }}"; + + // Grab entry for the current version so we use it later + let currentVersionEntry = data.filter(entry => entry.version == currentVersion)[0]; // create links to the corresponding page in the other docs versions $.each(data, function(index, entry) { @@ -87,19 +88,25 @@ // If this entry is the one we wish to direct to // And this entry is not currently active // then add a banner to direct people there - if ((entry.version == directToVersion) && (directToVersion != currentVersion)) { + if ((entry.preferred == "true") && (entry.version != currentVersion)) { + if (currentVersionEntry.type == "development") { + var currentVersionType = "development version"; + } else if (currentVersionEntry.type == "prerelease") { + var currentVersionType = "release candidate"; + } else { + var currentVersionType = "previous release"; + }; placeholder = document.getElementById("header-version-warning-placeholder"); placeholder.insertAdjacentHTML("afterend", `
- This documentation is for an unreleased or outdated version. + This documentation is for a ${currentVersionType}.
`); console.log("[PST]: Inserted version warning banner..."); } - }); }); 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 index dc29d79ae..d90aecb21 100644 --- 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 @@ -1,5 +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 and theme_switcher.get('direct_to_version') %} +{%- if theme_switcher %} +
{% endif -%} From 9895d34e8b658ed530db00ca35962130c957c847 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Fri, 1 Jul 2022 23:30:35 +0200 Subject: [PATCH 5/5] Descriptoin --- docs/_static/switcher.json | 2 +- docs/user_guide/configuring.rst | 12 ++++-------- .../components/version-switcher.html | 10 ++++------ 3 files changed, 9 insertions(+), 15 deletions(-) diff --git a/docs/_static/switcher.json b/docs/_static/switcher.json index 33f5fd23b..4a6e4ba3b 100644 --- a/docs/_static/switcher.json +++ b/docs/_static/switcher.json @@ -2,7 +2,7 @@ { "name": "dev", "version": "latest", - "type": "development", + "description": "the development version", "url": "https://pydata-sphinx-theme.readthedocs.io/en/latest/" }, { diff --git a/docs/user_guide/configuring.rst b/docs/user_guide/configuring.rst index 515a387c5..91b4f8e74 100644 --- a/docs/user_guide/configuring.rst +++ b/docs/user_guide/configuring.rst @@ -705,12 +705,8 @@ This is useful if you have many versions of your documentation (e.g. old release To activate this feature, add ``"preferred": "true"`` to one of the entries in your ``switcher.json`` file. This will mark it as the "preferred version" that other versions should direct to. -In addition, you may mark some versions with a ``"type"`` which will slightly modify the banner message displayed. -To do so, add ``"type": "development"`` to any entry with one of three options, described below. - -- ``"type": "release"`` (default if no type specified): a **previous release**. -- ``"type": "releasecandidate"``: a **release candidate**. -- ``"type": "development"``: a **development branch**. +In addition, you may mark versions with a ``"description"`` which will be displayed in the banner message. +If not given, the value of ``"description"`` will be ``"a previous release"``. For example, below we demonstrate a ``switcher.json`` with five entries: a development version, the latest release (which is preferred), a release candidate, and two previous releases. @@ -720,7 +716,7 @@ For example, below we demonstrate a ``switcher.json`` with five entries: a devel { "name": "v2.2dev0 (development)", "version": "v2.2dev0", - "type": "development", + "description": "a development version", "url": "https://mysite.org/en/2.1/index.html" }, { "name": "v2.1 (stable)", @@ -730,7 +726,7 @@ For example, below we demonstrate a ``switcher.json`` with five entries: a devel }, { "version": "2.1rc1", - "type": "releasecandidate", + "description": "a release candidate for 2.1" "url": "https://mysite.org/en/2.1rc1/index.html" }, { 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 8200c2451..a83f6401c 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 @@ -89,18 +89,16 @@ // And this entry is not currently active // then add a banner to direct people there if ((entry.preferred == "true") && (entry.version != currentVersion)) { - if (currentVersionEntry.type == "development") { - var currentVersionType = "development version"; - } else if (currentVersionEntry.type == "prerelease") { - var currentVersionType = "release candidate"; + if (currentVersionEntry.description) { + var currentVersionDescription = currentVersionEntry.description; } else { - var currentVersionType = "previous release"; + var currentVersionDescription = "a previous release"; }; placeholder = document.getElementById("header-version-warning-placeholder"); placeholder.insertAdjacentHTML("afterend", `
- This documentation is for a ${currentVersionType}. + This documentation is for ${currentVersionDescription}.