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

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(+)

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

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