[PATCH 1/3] docs: sphinx-static: switchers.js.in: remove duplicate for outdated versions

[PATCH 1/3] docs: sphinx-static: switchers.js.in: remove duplicate for outdated versions

[Quentin Schulz]

From: Quentin Schulz <quentin.schulz@theobroma-systems.com>

Since commit f2b069be8c307 "set_versions: Various improvements", an
outdated version will always appear in all_versions, meaning there'll
always be an exact match in the loop (just above the git context of this
patch) so there's no need to add the current_version to the dropdown
menu manually.

This issue showed up only for outdated versions of obsolete releases,
e.g. 3.2.3. In that case, 3.2.4 (latest version of the obsolete release)
will appear in the all_versions array in addition to 3.2.3, which means
the check on release series (3.2) will be matched twice, and 3.2.3 will
be printed once in the 3.2.4 loop because version != current_version and
once in the 3.2.3 because it is an exact match to an entry in
all_versions.

Cc: Quentin Schulz <foss+yocto@0leil.net>
Signed-off-by: Quentin Schulz <quentin.schulz@theobroma-systems.com>
---
 documentation/sphinx-static/switchers.js.in | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/documentation/sphinx-static/switchers.js.in b/documentation/sphinx-static/switchers.js.in
index 5d3a4d793..e7ef2ce5f 100644
--- a/documentation/sphinx-static/switchers.js.in
+++ b/documentation/sphinx-static/switchers.js.in
@@ -72,9 +72,6 @@ by https://git.yoctoproject.org/yocto-autobuilder-helper/tree/scripts/run-docs-b
             buf.push('<option value="' + version + '" selected="selected">' + title + '</option>');
         else
             buf.push('<option value="' + version + '">' + title + '</option>');
-
-        if (version != current_version)
-            buf.push('<option value="' + current_version + '" selected="selected">' + current_version + '</option>');
       } else {
         buf.push('<option value="' + version + '">' + title + '</option>');
       }
-- 
2.35.1

[PATCH 2/3] docs: set_versions.py: add information about obsolescence of a release

[Quentin Schulz]

From: Quentin Schulz <quentin.schulz@theobroma-systems.com>

This adds support for marking releases as obsolete to make the
detection algorithm smarter (in a later commit) than just checking if
it's older than dunfell.

Cc: Quentin Schulz <foss+yocto@0leil.net>
Signed-off-by: Quentin Schulz <quentin.schulz@theobroma-systems.com>
---
 documentation/set_versions.py               |  6 +++---
 documentation/sphinx-static/switchers.js.in | 12 ++++++------
 2 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/documentation/set_versions.py b/documentation/set_versions.py
index fceff4dbc..0fcbb993b 100755
--- a/documentation/set_versions.py
+++ b/documentation/set_versions.py
@@ -207,7 +207,7 @@ with open("sphinx-static/switchers.js.in", "r") as r, open("sphinx-static/switch
     lines = r.readlines()
     for line in lines:
         if "VERSIONS_PLACEHOLDER" in line:
-            w.write("    'dev': 'dev (%s)',\n" % release_series[devbranch])
+            w.write("    'dev': { 'title': 'dev (%s)', 'obsolete': false,},\n" % release_series[devbranch])
             for branch in activereleases:
                 if branch == devbranch:
                     continue
@@ -219,9 +219,9 @@ with open("sphinx-static/switchers.js.in", "r") as r, open("sphinx-static/switch
                 if versions[-1] != "0":
                     version = version + "." + versions[-1]
                 versions.append(version)
-                w.write("    '%s': '%s',\n" % (version, version))
+                w.write("    '%s': {'title': '%s', 'obsolete': %s,},\n" % (version, version, str(branch == ourseries).lower()))
             if ourversion not in versions and ourseries != devbranch:
-                w.write("    '%s': '%s',\n" % (ourversion, ourversion))
+                w.write("    '%s': {'title': '%s', 'obsolete': true,},\n" % (ourversion, ourversion))
         else:
             w.write(line)
 
diff --git a/documentation/sphinx-static/switchers.js.in b/documentation/sphinx-static/switchers.js.in
index e7ef2ce5f..5ae0325e6 100644
--- a/documentation/sphinx-static/switchers.js.in
+++ b/documentation/sphinx-static/switchers.js.in
@@ -65,15 +65,15 @@ by https://git.yoctoproject.org/yocto-autobuilder-helper/tree/scripts/run-docs-b
   function build_version_select(current_series, current_version) {
     var buf = ['<select>'];
 
-    $.each(all_versions, function(version, title) {
+    $.each(all_versions, function(version, vers_data) {
       var series = version.substr(0, 3);
       if (series == current_series) {
         if (version == current_version)
-            buf.push('<option value="' + version + '" selected="selected">' + title + '</option>');
-        else
-            buf.push('<option value="' + version + '">' + title + '</option>');
+            buf.push('<option value="' + version + '" selected="selected">' + vers_data["title"] + '</option>');
+	      else
+            buf.push('<option value="' + version + '">' + vers_data["title"] + '</option>');
       } else {
-        buf.push('<option value="' + version + '">' + title + '</option>');
+        buf.push('<option value="' + version + '">' + vers_data["title"] + '</option>');
       }
     });
 
@@ -223,7 +223,7 @@ by https://git.yoctoproject.org/yocto-autobuilder-helper/tree/scripts/run-docs-b
       $('#outdated-warning').html('Version ' + release + ' of the project is now considered obsolete, please select and use a more recent version');
       $('#outdated-warning').css('padding', '.5em');
     } else if (release != "dev") {
-      $.each(all_versions, function(version, title) {
+      $.each(all_versions, function(version, vers_data) {
         var series = version.substr(0, 3);
         if (series == current_series && version != release) {
           $('#outdated-warning').html('This document is for outdated version ' + release + ', you should select the latest release version in this series, ' + version + '.');
-- 
2.35.1

[PATCH 3/3] docs: sphinx-static: switchers.js.in: improve obsolete version detection

[Quentin Schulz]

From: Quentin Schulz <quentin.schulz@theobroma-systems.com>

Based on additional information per release, specifically with the
obsolescence status of a release, the obsolescence detection can now be
much smarter than just checking if the release is older than dunfell.

This is required because with LTS (dunfell for example) releases, it is
now possible to have LTS releases that are older than obsolete releases.

This means obsolete releases need to be tracked and only the release
version cannot be used as an indicator of obsolescence.

Let's use the obsolete field of the per-release data in the all_versions
dictionary to display correct warning messages.

The warning message is first about outdated version if there's a newer
one available (*even* if it is for an obsolete release, e.g. 3.0.1 will
say it's outdated and should select 3.0.4 version instead), then if the
version is the last of the release, show a warning message if the
release is obsolete.

Cc: Quentin Schulz <foss+yocto@0leil.net>
Signed-off-by: Quentin Schulz <quentin.schulz@theobroma-systems.com>
---
 documentation/sphinx-static/switchers.js.in | 19 ++++++++++++-------
 1 file changed, 12 insertions(+), 7 deletions(-)

diff --git a/documentation/sphinx-static/switchers.js.in b/documentation/sphinx-static/switchers.js.in
index 5ae0325e6..408e23a71 100644
--- a/documentation/sphinx-static/switchers.js.in
+++ b/documentation/sphinx-static/switchers.js.in
@@ -219,15 +219,20 @@ by https://git.yoctoproject.org/yocto-autobuilder-helper/tree/scripts/run-docs-b
     $('.doctype_switcher_placeholder').html(doctype_select);
     $('.doctype_switcher_placeholder select').bind('change', on_doctype_switch);
 
-    if (ver_compare(release, "3.1") < 0) {
-      $('#outdated-warning').html('Version ' + release + ' of the project is now considered obsolete, please select and use a more recent version');
-      $('#outdated-warning').css('padding', '.5em');
-    } else if (release != "dev") {
+    if (release != "dev") {
       $.each(all_versions, function(version, vers_data) {
         var series = version.substr(0, 3);
-        if (series == current_series && version != release) {
-          $('#outdated-warning').html('This document is for outdated version ' + release + ', you should select the latest release version in this series, ' + version + '.');
-          $('#outdated-warning').css('padding', '.5em');
+        if (series == current_series) {
+          if (version != release) {
+            $('#outdated-warning').html('This document is for outdated version ' + release + ', you should select the latest release version in this series, ' + version + '.');
+            $('#outdated-warning').css('padding', '.5em');
+            return false;
+          }
+          if (vers_data["obsolete"]) {
+            $('#outdated-warning').html('Version ' + release + ' of the project is now considered obsolete, please select and use a more recent version');
+            $('#outdated-warning').css('padding', '.5em');
+            return false;
+          }
         }
       });
     }
-- 
2.35.1

Re: [docs] [PATCH 3/3] docs: sphinx-static: switchers.js.in: improve obsolete version detection

[Michael Opdenacker]

Hi Quentin,

On 4/14/22 13:33, Quentin Schulz wrote:
> From: Quentin Schulz <quentin.schulz@theobroma-systems.com>
>
> Based on additional information per release, specifically with the
> obsolescence status of a release, the obsolescence detection can now be
> much smarter than just checking if the release is older than dunfell.
>
> This is required because with LTS (dunfell for example) releases, it is
> now possible to have LTS releases that are older than obsolete releases.
>
> This means obsolete releases need to be tracked and only the release
> version cannot be used as an indicator of obsolescence.
>
> Let's use the obsolete field of the per-release data in the all_versions
> dictionary to display correct warning messages.
>
> The warning message is first about outdated version if there's a newer
> one available (*even* if it is for an obsolete release, e.g. 3.0.1 will
> say it's outdated and should select 3.0.4 version instead), then if the
> version is the last of the release, show a warning message if the
> release is obsolete.
>
> Cc: Quentin Schulz <foss+yocto@0leil.net>
> Signed-off-by: Quentin Schulz <quentin.schulz@theobroma-systems.com>
> ---
>  documentation/sphinx-static/switchers.js.in | 19 ++++++++++++-------
>  1 file changed, 12 insertions(+), 7 deletions(-)


Thanks for the whole patch series.
The changes seem to make sense.
I merged them into master-next.

Thanks again
Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com