[PATCH 1/3] docs: set_versions.py: mark as obsolete only branches or not-latest tags which are from an obsolete release

[PATCH 1/3] docs: set_versions.py: mark as obsolete only branches or not-latest tags which are from an obsolete release

[Quentin Schulz]

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

Branches are identified by their .999 version suffix which means they
will never be matched in the forloop above this git context. Therefore,
branches will match the condition. However, branches are not necessarily
obsolete (e.g. dunfell, honister and kirkstone today), so let's mark as
obsolete the branches which are from obsolete releases.

The same applies to not-latest tags of supported releases. The obsolete
and outdate warning messages are handled separately and only obsolete is
handled here, and not-latest tags of supported releases are technically
not obsolete, so let's not mark them as so.

Cc: Quentin Schulz <foss+yocto@0leil.net>
Signed-off-by: Quentin Schulz <quentin.schulz@theobroma-systems.com>
---
 documentation/set_versions.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/set_versions.py b/documentation/set_versions.py
index 8ae02b11f..dfa2dc269 100755
--- a/documentation/set_versions.py
+++ b/documentation/set_versions.py
@@ -218,7 +218,7 @@ with open("sphinx-static/switchers.js.in", "r") as r, open("sphinx-static/switch
                 versions.append(version)
                 w.write("    '%s': {'title': '%s', 'obsolete': %s,},\n" % (version, version, str(branch not in activereleases).lower()))
             if ourversion not in versions and ourseries != devbranch:
-                w.write("    '%s': {'title': '%s', 'obsolete': true,},\n" % (ourversion, ourversion))
+                w.write("    '%s': {'title': '%s', 'obsolete': %s,},\n" % (ourversion, ourversion, str(ourseries not in activereleases).lower()))
         else:
             w.write(line)
 
-- 
2.35.1

[PATCH 2/3] docs: sphinx-static: switchers.js.in: rename all_versions to switcher_versions

[Quentin Schulz]

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

This array only contains versions that can be selected through the
dropdown menu for switching between supported versions.

Therefore, let's rename it to switcher_versions to make its usecase
clearer.

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

diff --git a/documentation/sphinx-static/switchers.js.in b/documentation/sphinx-static/switchers.js.in
index 408e23a71..a44edbcab 100644
--- a/documentation/sphinx-static/switchers.js.in
+++ b/documentation/sphinx-static/switchers.js.in
@@ -9,7 +9,7 @@ by https://git.yoctoproject.org/yocto-autobuilder-helper/tree/scripts/run-docs-b
 (function() {
   'use strict';
 
-  var all_versions = {
+  var switcher_versions = {
     VERSIONS_PLACEHOLDER
   };
 
@@ -65,7 +65,7 @@ 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, vers_data) {
+    $.each(switcher_versions, function(version, vers_data) {
       var series = version.substr(0, 3);
       if (series == current_series) {
         if (version == current_version)
@@ -220,7 +220,7 @@ by https://git.yoctoproject.org/yocto-autobuilder-helper/tree/scripts/run-docs-b
     $('.doctype_switcher_placeholder select').bind('change', on_doctype_switch);
 
     if (release != "dev") {
-      $.each(all_versions, function(version, vers_data) {
+      $.each(switcher_versions, function(version, vers_data) {
         var series = version.substr(0, 3);
         if (series == current_series) {
           if (version != release) {
-- 
2.35.1

[PATCH 3/3] docs: sphinx-static: switchers.js.in: fix broken switcher for branches

[Quentin Schulz]

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

The switcher expects URL subpath to match the "release" used by sphinx
to build the documentation. Branches, however, are put in a subpath
after their name (e.g. dunfell) while sphinx sets the "release" to
X.Y.999. This means the switcher cannot replace correctly the path to
switch between releases/versions.

Let set_versions.py inject the list of release names into the
switchers.js.in file so it can check whether the subpath is one of the
release names in which case it needs to be stripped.

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

diff --git a/documentation/set_versions.py b/documentation/set_versions.py
index dfa2dc269..386cff366 100755
--- a/documentation/set_versions.py
+++ b/documentation/set_versions.py
@@ -203,6 +203,9 @@ versions = []
 with open("sphinx-static/switchers.js.in", "r") as r, open("sphinx-static/switchers.js", "w") as w:
     lines = r.readlines()
     for line in lines:
+        if "ALL_VERSIONS_PLACEHOLDER" in line:
+            w.write(str(list(release_series.keys())))
+            continue
         if "VERSIONS_PLACEHOLDER" in line:
             w.write("    'dev': { 'title': 'dev (%s)', 'obsolete': false,},\n" % release_series[devbranch])
             for branch in activereleases + ([ourseries] if ourseries not in activereleases else []):
diff --git a/documentation/sphinx-static/switchers.js.in b/documentation/sphinx-static/switchers.js.in
index a44edbcab..2bc18160d 100644
--- a/documentation/sphinx-static/switchers.js.in
+++ b/documentation/sphinx-static/switchers.js.in
@@ -9,6 +9,10 @@ by https://git.yoctoproject.org/yocto-autobuilder-helper/tree/scripts/run-docs-b
 (function() {
   'use strict';
 
+  var all_versions =
+	ALL_VERSIONS_PLACEHOLDER
+  ;
+
   var switcher_versions = {
     VERSIONS_PLACEHOLDER
   };
@@ -157,6 +161,14 @@ by https://git.yoctoproject.org/yocto-autobuilder-helper/tree/scripts/run-docs-b
         var new_url = docroot + new_versionpath + url.replace(docroot, "");
         var fallback_url = docroot + new_versionpath;
     } else {
+	// check for named releases (e.g. dunfell) in the subpath
+        $.each(all_versions, function(idx, name) {
+		if (docroot.endsWith('/' + name + '/')) {
+			current_version = name;
+			return false;
+		}
+	});
+
         var new_url = url.replace('/' + current_version + '/', '/' + new_versionpath);
         var fallback_url = new_url.replace(url.replace(docroot, ""), "");
     }
-- 
2.35.1

Re: [docs] [PATCH 3/3] docs: sphinx-static: switchers.js.in: fix broken switcher for branches

[Richard Purdie]

On Wed, 2022-04-20 at 13:24 +0200, Quentin Schulz wrote:
> From: Quentin Schulz <quentin.schulz@theobroma-systems.com>
> 
> The switcher expects URL subpath to match the "release" used by sphinx
> to build the documentation. Branches, however, are put in a subpath
> after their name (e.g. dunfell) while sphinx sets the "release" to
> X.Y.999. This means the switcher cannot replace correctly the path to
> switch between releases/versions.
> 
> Let set_versions.py inject the list of release names into the
> switchers.js.in file so it can check whether the subpath is one of the
> release names in which case it needs to be stripped.
> 
> Cc: Quentin Schulz <foss+yocto@0leil.net>
> Signed-off-by: Quentin Schulz <quentin.schulz@theobroma-systems.com>
> ---
>  documentation/set_versions.py               |  3 +++
>  documentation/sphinx-static/switchers.js.in | 12 ++++++++++++
>  2 files changed, 15 insertions(+)
> 
> diff --git a/documentation/set_versions.py b/documentation/set_versions.py
> index dfa2dc269..386cff366 100755
> --- a/documentation/set_versions.py
> +++ b/documentation/set_versions.py
> @@ -203,6 +203,9 @@ versions = []
>  with open("sphinx-static/switchers.js.in", "r") as r, open("sphinx-static/switchers.js", "w") as w:
>      lines = r.readlines()
>      for line in lines:
> +        if "ALL_VERSIONS_PLACEHOLDER" in line:
> +            w.write(str(list(release_series.keys())))
> +            continue
>          if "VERSIONS_PLACEHOLDER" in line:
>              w.write("    'dev': { 'title': 'dev (%s)', 'obsolete': false,},\n" % release_series[devbranch])
>              for branch in activereleases + ([ourseries] if ourseries not in activereleases else []):
> diff --git a/documentation/sphinx-static/switchers.js.in b/documentation/sphinx-static/switchers.js.in
> index a44edbcab..2bc18160d 100644
> --- a/documentation/sphinx-static/switchers.js.in
> +++ b/documentation/sphinx-static/switchers.js.in
> @@ -9,6 +9,10 @@ by https://git.yoctoproject.org/yocto-autobuilder-helper/tree/scripts/run-docs-b
>  (function() {
>    'use strict';
>  
> +  var all_versions =
> +	ALL_VERSIONS_PLACEHOLDER
> +  ;
> +
>    var switcher_versions = {
>      VERSIONS_PLACEHOLDER
>    };
> @@ -157,6 +161,14 @@ by https://git.yoctoproject.org/yocto-autobuilder-helper/tree/scripts/run-docs-b
>          var new_url = docroot + new_versionpath + url.replace(docroot, "");
>          var fallback_url = docroot + new_versionpath;
>      } else {
> +	// check for named releases (e.g. dunfell) in the subpath
> +        $.each(all_versions, function(idx, name) {
> +		if (docroot.endsWith('/' + name + '/')) {
> +			current_version = name;
> +			return false;
> +		}
> +	});
> +
>          var new_url = url.replace('/' + current_version + '/', '/' + new_versionpath);
>          var fallback_url = new_url.replace(url.replace(docroot, ""), "");
>      }

Should this be called "all_releases" or "release_series" instead? It isn't
really a version list?

Cheers,

Richard

Re: [docs] [PATCH 1/3] docs: set_versions.py: mark as obsolete only branches or not-latest tags which are from an obsolete release

[Richard Purdie]

On Wed, 2022-04-20 at 13:24 +0200, Quentin Schulz wrote:
> From: Quentin Schulz <quentin.schulz@theobroma-systems.com>
> 
> Branches are identified by their .999 version suffix which means they
> will never be matched in the forloop above this git context. Therefore,
> branches will match the condition. However, branches are not necessarily
> obsolete (e.g. dunfell, honister and kirkstone today), so let's mark as
> obsolete the branches which are from obsolete releases.
> 
> The same applies to not-latest tags of supported releases. The obsolete
> and outdate warning messages are handled separately and only obsolete is
> handled here, and not-latest tags of supported releases are technically
> not obsolete, so let's not mark them as so.

I'm struggling to parse that last sentence. I think it needs a small tweak to
break it up into two pieces:

The obsolete and outdate warning messages are handled separately and only
obsolete is handled here. The not-latest tags of supported releases are
technically not obsolete, so let's not mark them as so.

Cheers,

Richard

Re: [docs] [PATCH 3/3] docs: sphinx-static: switchers.js.in: fix broken switcher for branches

[Quentin Schulz]

Hi Richard,

On 4/20/22 13:44, Richard Purdie wrote:
> On Wed, 2022-04-20 at 13:24 +0200, Quentin Schulz wrote:
>> From: Quentin Schulz <quentin.schulz@theobroma-systems.com>
>>
>> The switcher expects URL subpath to match the "release" used by sphinx
>> to build the documentation. Branches, however, are put in a subpath
>> after their name (e.g. dunfell) while sphinx sets the "release" to
>> X.Y.999. This means the switcher cannot replace correctly the path to
>> switch between releases/versions.
>>
>> Let set_versions.py inject the list of release names into the
>> switchers.js.in file so it can check whether the subpath is one of the
>> release names in which case it needs to be stripped.
>>
>> Cc: Quentin Schulz <foss+yocto@0leil.net>
>> Signed-off-by: Quentin Schulz <quentin.schulz@theobroma-systems.com>
>> ---
>>   documentation/set_versions.py               |  3 +++
>>   documentation/sphinx-static/switchers.js.in | 12 ++++++++++++
>>   2 files changed, 15 insertions(+)
>>
>> diff --git a/documentation/set_versions.py b/documentation/set_versions.py
>> index dfa2dc269..386cff366 100755
>> --- a/documentation/set_versions.py
>> +++ b/documentation/set_versions.py
>> @@ -203,6 +203,9 @@ versions = []
>>   with open("sphinx-static/switchers.js.in", "r") as r, open("sphinx-static/switchers.js", "w") as w:
>>       lines = r.readlines()
>>       for line in lines:
>> +        if "ALL_VERSIONS_PLACEHOLDER" in line:
>> +            w.write(str(list(release_series.keys())))
>> +            continue
>>           if "VERSIONS_PLACEHOLDER" in line:
>>               w.write("    'dev': { 'title': 'dev (%s)', 'obsolete': false,},\n" % release_series[devbranch])
>>               for branch in activereleases + ([ourseries] if ourseries not in activereleases else []):
>> diff --git a/documentation/sphinx-static/switchers.js.in b/documentation/sphinx-static/switchers.js.in
>> index a44edbcab..2bc18160d 100644
>> --- a/documentation/sphinx-static/switchers.js.in
>> +++ b/documentation/sphinx-static/switchers.js.in
>> @@ -9,6 +9,10 @@ by https://urldefense.proofpoint.com/v2/url?u=https-3A__git.yoctoproject.org_yocto-2Dautobuilder-2Dhelper_tree_scripts_run-2Ddocs-2Db&d=DwICaQ&c=_sEr5x9kUWhuk4_nFwjJtA&r=LYjLexDn7rXIzVmkNPvw5ymA1XTSqHGq8yBP6m6qZZ4njZguQhZhkI_-172IIy1t&m=g-IQJeaTqTJrY4BEqvN3SYYzip0oERxzLTCgmnPAx_ep3sLUM64WVRzszk1jAmS4&s=R2xrm2Qom6YqGo2VA3kFxq5WbFofQq4MQ4QnDuOiuIQ&e=
>>   (function() {
>>     'use strict';
>>   
>> +  var all_versions =
>> +	ALL_VERSIONS_PLACEHOLDER
>> +  ;
>> +
>>     var switcher_versions = {
>>       VERSIONS_PLACEHOLDER
>>     };
>> @@ -157,6 +161,14 @@ by https://urldefense.proofpoint.com/v2/url?u=https-3A__git.yoctoproject.org_yocto-2Dautobuilder-2Dhelper_tree_scripts_run-2Ddocs-2Db&d=DwICaQ&c=_sEr5x9kUWhuk4_nFwjJtA&r=LYjLexDn7rXIzVmkNPvw5ymA1XTSqHGq8yBP6m6qZZ4njZguQhZhkI_-172IIy1t&m=g-IQJeaTqTJrY4BEqvN3SYYzip0oERxzLTCgmnPAx_ep3sLUM64WVRzszk1jAmS4&s=R2xrm2Qom6YqGo2VA3kFxq5WbFofQq4MQ4QnDuOiuIQ&e=
>>           var new_url = docroot + new_versionpath + url.replace(docroot, "");
>>           var fallback_url = docroot + new_versionpath;
>>       } else {
>> +	// check for named releases (e.g. dunfell) in the subpath
>> +        $.each(all_versions, function(idx, name) {
>> +		if (docroot.endsWith('/' + name + '/')) {
>> +			current_version = name;
>> +			return false;
>> +		}
>> +	});
>> +
>>           var new_url = url.replace('/' + current_version + '/', '/' + new_versionpath);
>>           var fallback_url = new_url.replace(url.replace(docroot, ""), "");
>>       }
> 
> Should this be called "all_releases" or "release_series" instead? It isn't
> really a version list?
> 

It is a list of release names only, of all releases ever published. I 
named it this way in anticipation that we'll need to make this a 
dictionary to store more info later on. all_releases works for me, 
thanks for the suggestion.

Cheers,
Quentin