[PATCH 1/4] docs: sphinx-static: switchers.js: add release name to dropdown menu

[PATCH 1/4] docs: sphinx-static: switchers.js: add release name to dropdown menu

[Quentin Schulz]

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

diff --git a/documentation/sphinx-static/switchers.js b/documentation/sphinx-static/switchers.js
index 1e37b625a..cb55e35c8 100644
--- a/documentation/sphinx-static/switchers.js
+++ b/documentation/sphinx-static/switchers.js
@@ -3,11 +3,11 @@
 
   var all_versions = {
     'dev': 'dev (3.4)',
-    '3.3.3': '3.3.3',
-    '3.2.4': '3.2.4',
-    '3.1.11': '3.1.11',
-    '3.0.4': '3.0.4',
-    '2.7.4': '2.7.4',
+    '3.3.3': 'hardknott (3.3.3)',
+    '3.2.4': 'gatesgarth (3.2.4)',
+    '3.1.11': 'dunfell (3.1.11)',
+    '3.0.4': 'zeus (3.0.4)',
+    '2.7.4': 'warrior (2.7.4)',
   };
 
   var all_doctypes = {
-- 
2.31.1

[PATCH 2/4] docs: sphinx-static: switchers.js: correctly highlight obsolete releases

[Quentin Schulz]

Currently, only releases before 3.1 are marked as obsolete even though
3.2 is already obsolete too.

Since 3.1 is an LTS and is still maintained, it needs to not be marked
as obsolete, unlike 3.2. Therefore, LTS series are now also tested
against before marking a release as obsolete.

This makes non-LTS, non-latest releases obsolete.

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

diff --git a/documentation/sphinx-static/switchers.js b/documentation/sphinx-static/switchers.js
index cb55e35c8..6038ae065 100644
--- a/documentation/sphinx-static/switchers.js
+++ b/documentation/sphinx-static/switchers.js
@@ -10,11 +10,22 @@
     '2.7.4': 'warrior (2.7.4)',
   };
 
+  var latest_release_series = '3.3'
+  var lts_series = [
+	'3.1',
+  ]
+
   var all_doctypes = {
       'single': 'Individual Webpages',
       'mega': "All-in-one 'Mega' Manual",
   };
 
+  function ver_obsolete(curr) {
+    var series = curr.substr(0, 3);
+    return ver_compare(curr, latest_release_series) < 0 &&
+	    lts_series.indexOf(series) >= 0;
+  }
+
   // Simple version comparision
   // Return 1 if a > b
   // Return -1 if a < b
@@ -219,7 +230,7 @@
     $('.doctype_switcher_placeholder').html(doctype_select);
     $('.doctype_switcher_placeholder select').bind('change', on_doctype_switch);
 
-    if (ver_compare(release, "3.1") < 0) {
+    if (ver_obsolete(release) != 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") {
-- 
2.31.1

[PATCH 3/4] docs: sphinx-static: switchers.js: point to newer release in outdated warning

[Quentin Schulz]

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

diff --git a/documentation/sphinx-static/switchers.js b/documentation/sphinx-static/switchers.js
index 6038ae065..35b9a8c81 100644
--- a/documentation/sphinx-static/switchers.js
+++ b/documentation/sphinx-static/switchers.js
@@ -221,6 +221,7 @@
     var current_doctype = doctype_segment_from_url(window.location.href);
     var current_series = release.substr(0, 3);
     var version_select = build_version_select(current_series, release);
+    var orig = window.location.href;
 
     $('.version_switcher_placeholder').html(version_select);
     $('.version_switcher_placeholder select').bind('change', on_version_switch);
@@ -231,13 +232,13 @@
     $('.doctype_switcher_placeholder select').bind('change', on_doctype_switch);
 
     if (ver_obsolete(release) != 0) {
-      $('#outdated-warning').html('Version ' + release + ' of the project is now considered obsolete, please select and use a more recent version');
+      $('#outdated-warning').html('Version ' + release + ' of the project is now considered obsolete, please select and use a more recent version, e.g. <a href="' + orig.replace('/' + release, '/' + latest_release_series) + '">' + latest_release_series + '</a>.');
       $('#outdated-warning').css('padding', '.5em');
     } else if (release != "dev") {
       $.each(all_versions, function(version, title) {
         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').html('This document is for outdated version ' + release + ', you should select the latest release version in this series, <a href="' + orig.replace('/' + release, '/' + version) + '">' + version + '</a>.');
           $('#outdated-warning').css('padding', '.5em');
         }
       });
-- 
2.31.1

[PATCH 4/4] docs: sphinx-static: switchers.js: redirect doc series links to latest known dot release for given series

[Quentin Schulz]

This redirects e.g. 3.2 docs to 3.2.4 so that the docs are always
up-to-date for a given release.

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

diff --git a/documentation/sphinx-static/switchers.js b/documentation/sphinx-static/switchers.js
index 35b9a8c81..0dc947ea0 100644
--- a/documentation/sphinx-static/switchers.js
+++ b/documentation/sphinx-static/switchers.js
@@ -238,8 +238,19 @@
       $.each(all_versions, function(version, title) {
         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, <a href="' + orig.replace('/' + release, '/' + version) + '">' + version + '</a>.');
-          $('#outdated-warning').css('padding', '.5em');
+          // Redirect 3.2 to 3.2.4 but not 3.2.1 to 3.2.4
+          if (current_series == release) {
+            var url = orig.replace('/' + release, '/' + version);
+            $.ajax({
+              url: url,
+              success: function() {
+                window.location.href = url;
+              }
+            });
+	  } else {
+            $('#outdated-warning').html('This document is for outdated version ' + release + ', you should select the latest release version in this series, <a href="' + orig.replace('/' + release, '/' + version) + '">' + version + '</a>.');
+            $('#outdated-warning').css('padding', '.5em');
+	  }
         }
       });
     }
-- 
2.31.1

Re: [PATCH 4/4] docs: sphinx-static: switchers.js: redirect doc series links to latest known dot release for given series

[Quentin Schulz]

On Tue, Sep 28, 2021 at 06:22:02PM +0200, Quentin Schulz wrote:
> This redirects e.g. 3.2 docs to 3.2.4 so that the docs are always
> up-to-date for a given release.
> 

I realize this might be a "bad" idea since 3.2 is basically 3.2.0 for
us. So sending this patch anyway just to start a small discussion?
Should 3.2 be a "meta" tag in the docs and have 3.2.0 instead of 3.2 for
the first release of a... release?

Does any of this make sense?

Cheers,
Quentin

> Cc: Quentin Schulz <foss@0leil.net>
> Signed-off-by: Quentin Schulz <quentin.schulz@theobroma-systems.com>
> ---
>  documentation/sphinx-static/switchers.js | 15 +++++++++++++--
>  1 file changed, 13 insertions(+), 2 deletions(-)
> 
> diff --git a/documentation/sphinx-static/switchers.js b/documentation/sphinx-static/switchers.js
> index 35b9a8c81..0dc947ea0 100644
> --- a/documentation/sphinx-static/switchers.js
> +++ b/documentation/sphinx-static/switchers.js
> @@ -238,8 +238,19 @@
>        $.each(all_versions, function(version, title) {
>          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, <a href="' + orig.replace('/' + release, '/' + version) + '">' + version + '</a>.');
> -          $('#outdated-warning').css('padding', '.5em');
> +          // Redirect 3.2 to 3.2.4 but not 3.2.1 to 3.2.4
> +          if (current_series == release) {
> +            var url = orig.replace('/' + release, '/' + version);
> +            $.ajax({
> +              url: url,
> +              success: function() {
> +                window.location.href = url;
> +              }
> +            });
> +	  } else {
> +            $('#outdated-warning').html('This document is for outdated version ' + release + ', you should select the latest release version in this series, <a href="' + orig.replace('/' + release, '/' + version) + '">' + version + '</a>.');
> +            $('#outdated-warning').css('padding', '.5em');
> +	  }
>          }
>        });
>      }
> -- 
> 2.31.1
> 

Re: [docs] [PATCH 2/4] docs: sphinx-static: switchers.js: correctly highlight obsolete releases

[Nicolas Dechesne]

hey Quentin!

thanks for getting back to this... we've known this is an issue since
we've migrated.. but never been brave enough to try to fix ;)

On Tue, Sep 28, 2021 at 6:22 PM Quentin Schulz
<quentin.schulz@theobroma-systems.com> wrote:
>
> Currently, only releases before 3.1 are marked as obsolete even though
> 3.2 is already obsolete too.
>
> Since 3.1 is an LTS and is still maintained, it needs to not be marked
> as obsolete, unlike 3.2. Therefore, LTS series are now also tested
> against before marking a release as obsolete.
>
> This makes non-LTS, non-latest releases obsolete.
>
> Cc: Quentin Schulz <foss@0leil.net>
> Signed-off-by: Quentin Schulz <quentin.schulz@theobroma-systems.com>
> ---
>  documentation/sphinx-static/switchers.js | 13 ++++++++++++-
>  1 file changed, 12 insertions(+), 1 deletion(-)
>
> diff --git a/documentation/sphinx-static/switchers.js b/documentation/sphinx-static/switchers.js
> index cb55e35c8..6038ae065 100644
> --- a/documentation/sphinx-static/switchers.js
> +++ b/documentation/sphinx-static/switchers.js
> @@ -10,11 +10,22 @@
>      '2.7.4': 'warrior (2.7.4)',
>    };
>
> +  var latest_release_series = '3.3'
> +  var lts_series = [
> +       '3.1',
> +  ]
> +


in the past I did a few experiments.. What I think would be ideal is
if the 'release' information was actually managed outside of yp-docs,
like it was the case with the previous documentation. It was a task
for the 'release engineer' to maintain that:
http://api-v1.yoctoproject.org/documentation-api
http://api-v1.yoctoproject.org/documentation-api/archived

And the website was loading these files to display the documentation
dynamically.

Since the information is now in git, it's very cumbersome, since
switchers.js exists in each branch.. so fix that we have a big hack in
the deployment script [1], which does:

# Update switchers.js with the copy from master ypdocs
cd $outputdir
find . -name switchers.js -not -path ./_static/switchers.js -exec cp
./_static/switchers.js {} \;

I've faced issues when trying to load an 'external' XML file into the
docs website (something to deal with proxy or permissions..).. so I
tried to have the 'release information' in one structure (in
switchers.js as an intermediate step), which looks like that:

+  var all_versions = [
+    {'version' : 'dev', 'name' : 'dev (3.3)', 'show' : 'yes'},
+
+    {'version' : '3.2',   'show' : 'yes'},
+
+    {'version' : '3.1.3', 'show' : 'yes', 'docbook' : 'yes'},
+    {'version' : '3.1.2', 'show' : 'yes', 'docbook' : 'yes', 'state'
: 'outdated'},
+    {'version' : '3.1.1', 'show' : 'yes', 'docbook' : 'yes', 'state'
: 'outdated'},
+    {'version' : '3.1',   'show' : 'yes', 'docbook' : 'yes', 'state'
: 'outdated'},
+
+    {'version' : '3.0.4', 'show' : 'yes', 'docbook' : 'yes', 'state'
: 'obsolete'},
+    {'version' : '3.0.3', 'show' : 'no', 'docbook' : 'yes', 'state' :
'obsolete'},
+    {'version' : '3.0.2', 'show' : 'no', 'docbook' : 'yes', 'state' :
'obsolete'},
+    {'version' : '3.0.1', 'show' : 'no', 'docbook' : 'yes', 'state' :
'obsolete'},
+    {'version' : '3.0',   'show' : 'no', 'docbook' : 'yes', 'state' :
'obsolete'},
+
+    {'version' : '2.7.4', 'show' : 'yes', 'docbook' : 'yes', 'state'
: 'obsolete'},
+    {'version' : '2.7.3', 'show' : 'no', 'docbook' : 'yes', 'state' :
'obsolete'},
+    {'version' : '2.7.2', 'show' : 'no', 'docbook' : 'yes', 'state' :
'obsolete'},
+    {'version' : '2.7.1', 'show' : 'no', 'docbook' : 'yes', 'state' :
'obsolete'},
+    {'version' : '2.7',   'show' : 'no', 'docbook' : 'yes', 'state' :
'obsolete'},
+  ];

At least, it becomes straightforward to insert a new release in the
table.. I am not sure I ever showed that.. so adding more to the
discussion.. I am sure the project would benefit from an overall
releases information database in a few other places, so that could be
extended.

 [1] http://git.yoctoproject.org/cgit/cgit.cgi/yocto-autobuilder-helper/tree/scripts/run-docs-build


>    var all_doctypes = {
>        'single': 'Individual Webpages',
>        'mega': "All-in-one 'Mega' Manual",
>    };
>
> +  function ver_obsolete(curr) {
> +    var series = curr.substr(0, 3);
> +    return ver_compare(curr, latest_release_series) < 0 &&
> +           lts_series.indexOf(series) >= 0;
> +  }
> +
>    // Simple version comparision
>    // Return 1 if a > b
>    // Return -1 if a < b
> @@ -219,7 +230,7 @@
>      $('.doctype_switcher_placeholder').html(doctype_select);
>      $('.doctype_switcher_placeholder select').bind('change', on_doctype_switch);
>
> -    if (ver_compare(release, "3.1") < 0) {
> +    if (ver_obsolete(release) != 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") {
> --
> 2.31.1
>
>
> -=-=-=-=-=-=-=-=-=-=-=-
> Links: You receive all messages sent to this group.
> View/Reply Online (#1900): https://lists.yoctoproject.org/g/docs/message/1900
> Mute This Topic: https://lists.yoctoproject.org/mt/85928522/1279857
> Group Owner: docs+owner@lists.yoctoproject.org
> Unsubscribe: https://lists.yoctoproject.org/g/docs/unsub [nicolas.dechesne@linaro.org]
> -=-=-=-=-=-=-=-=-=-=-=-
>

Re: [docs] [PATCH 2/4] docs: sphinx-static: switchers.js: correctly highlight obsolete releases

[Quentin Schulz]

Hi Nicolas,

On Tue, Sep 28, 2021 at 07:21:08PM +0200, Nicolas Dechesne wrote:
> hey Quentin!
> 
> thanks for getting back to this... we've known this is an issue since
> we've migrated.. but never been brave enough to try to fix ;)
> 
> On Tue, Sep 28, 2021 at 6:22 PM Quentin Schulz
> <quentin.schulz@theobroma-systems.com> wrote:
> >
> > Currently, only releases before 3.1 are marked as obsolete even though
> > 3.2 is already obsolete too.
> >
> > Since 3.1 is an LTS and is still maintained, it needs to not be marked
> > as obsolete, unlike 3.2. Therefore, LTS series are now also tested
> > against before marking a release as obsolete.
> >
> > This makes non-LTS, non-latest releases obsolete.
> >
> > Cc: Quentin Schulz <foss@0leil.net>
> > Signed-off-by: Quentin Schulz <quentin.schulz@theobroma-systems.com>
> > ---
> >  documentation/sphinx-static/switchers.js | 13 ++++++++++++-
> >  1 file changed, 12 insertions(+), 1 deletion(-)
> >
> > diff --git a/documentation/sphinx-static/switchers.js b/documentation/sphinx-static/switchers.js
> > index cb55e35c8..6038ae065 100644
> > --- a/documentation/sphinx-static/switchers.js
> > +++ b/documentation/sphinx-static/switchers.js
> > @@ -10,11 +10,22 @@
> >      '2.7.4': 'warrior (2.7.4)',
> >    };
> >
> > +  var latest_release_series = '3.3'
> > +  var lts_series = [
> > +       '3.1',
> > +  ]
> > +
> 
> 
> in the past I did a few experiments.. What I think would be ideal is
> if the 'release' information was actually managed outside of yp-docs,
> like it was the case with the previous documentation. It was a task
> for the 'release engineer' to maintain that:
> https://urldefense.proofpoint.com/v2/url?u=http-3A__api-2Dv1.yoctoproject.org_documentation-2Dapi&d=DwIBaQ&c=_sEr5x9kUWhuk4_nFwjJtA&r=LYjLexDn7rXIzVmkNPvw5ymA1XTSqHGq8yBP6m6qZZ4njZguQhZhkI_-172IIy1t&m=IkqJJb6C5WoayEw2QGUj-ZxPis-lTJKhRZGrreYumxY&s=gAwVxTehvj2VPr8tpwyGprny9CMsqa1_i48u0nlVQTE&e= 
> https://urldefense.proofpoint.com/v2/url?u=http-3A__api-2Dv1.yoctoproject.org_documentation-2Dapi_archived&d=DwIBaQ&c=_sEr5x9kUWhuk4_nFwjJtA&r=LYjLexDn7rXIzVmkNPvw5ymA1XTSqHGq8yBP6m6qZZ4njZguQhZhkI_-172IIy1t&m=IkqJJb6C5WoayEw2QGUj-ZxPis-lTJKhRZGrreYumxY&s=wz3yuYLM3LWMhGMobBRlz4F0xU9vhjRSQelKpuULkbY&e= 
> 
> And the website was loading these files to display the documentation
> dynamically.
> 
> Since the information is now in git, it's very cumbersome, since
> switchers.js exists in each branch.. so fix that we have a big hack in
> the deployment script [1], which does:
> 
> # Update switchers.js with the copy from master ypdocs
> cd $outputdir
> find . -name switchers.js -not -path ./_static/switchers.js -exec cp
> ./_static/switchers.js {} \;
> 

This is a different topic but yes we should settle on some solution that
is better than this. We could have a separate git repo somewhere for
that file. Then I can think of two solutions:

1) git clone this repo as part of the documentation
 publishing/development, which is "nicer" because it's explicit the
 switchers.js is the same for all releases but it's still just a cleaner
 way to implement the find command above,

2) have the web server serve this js in a
 docs.yoctoproject.org/somepath/switchers.js and add this path to the
 sphinx template, though we would need to think of a way to not need
 internet access on local development but I'm sure we can think of some
 hackish way :)

Also, I would very much like we have a similar mechanism for the
theme_override.css for Sphinx because I've fixed a few things in the
last few months and those aren't shown on old releases.

> I've faced issues when trying to load an 'external' XML file into the
> docs website (something to deal with proxy or permissions..).. so I
> tried to have the 'release information' in one structure (in
> switchers.js as an intermediate step), which looks like that:
> 
> +  var all_versions = [
> +    {'version' : 'dev', 'name' : 'dev (3.3)', 'show' : 'yes'},
> +
> +    {'version' : '3.2',   'show' : 'yes'},
> +
> +    {'version' : '3.1.3', 'show' : 'yes', 'docbook' : 'yes'},
> +    {'version' : '3.1.2', 'show' : 'yes', 'docbook' : 'yes', 'state'
> : 'outdated'},
> +    {'version' : '3.1.1', 'show' : 'yes', 'docbook' : 'yes', 'state'
> : 'outdated'},
> +    {'version' : '3.1',   'show' : 'yes', 'docbook' : 'yes', 'state'
> : 'outdated'},
> +
> +    {'version' : '3.0.4', 'show' : 'yes', 'docbook' : 'yes', 'state'
> : 'obsolete'},
> +    {'version' : '3.0.3', 'show' : 'no', 'docbook' : 'yes', 'state' :
> 'obsolete'},
> +    {'version' : '3.0.2', 'show' : 'no', 'docbook' : 'yes', 'state' :
> 'obsolete'},
> +    {'version' : '3.0.1', 'show' : 'no', 'docbook' : 'yes', 'state' :
> 'obsolete'},
> +    {'version' : '3.0',   'show' : 'no', 'docbook' : 'yes', 'state' :
> 'obsolete'},
> +
> +    {'version' : '2.7.4', 'show' : 'yes', 'docbook' : 'yes', 'state'
> : 'obsolete'},
> +    {'version' : '2.7.3', 'show' : 'no', 'docbook' : 'yes', 'state' :
> 'obsolete'},
> +    {'version' : '2.7.2', 'show' : 'no', 'docbook' : 'yes', 'state' :
> 'obsolete'},
> +    {'version' : '2.7.1', 'show' : 'no', 'docbook' : 'yes', 'state' :
> 'obsolete'},
> +    {'version' : '2.7',   'show' : 'no', 'docbook' : 'yes', 'state' :
> 'obsolete'},
> +  ];
> 
> At least, it becomes straightforward to insert a new release in the
> table.. I am not sure I ever showed that.. so adding more to the
> discussion.. I am sure the project would benefit from an overall
> releases information database in a few other places, so that could be
> extended.
> 
>  [1] https://urldefense.proofpoint.com/v2/url?u=http-3A__git.yoctoproject.org_cgit_cgit.cgi_yocto-2Dautobuilder-2Dhelper_tree_scripts_run-2Ddocs-2Dbuild&d=DwIBaQ&c=_sEr5x9kUWhuk4_nFwjJtA&r=LYjLexDn7rXIzVmkNPvw5ymA1XTSqHGq8yBP6m6qZZ4njZguQhZhkI_-172IIy1t&m=IkqJJb6C5WoayEw2QGUj-ZxPis-lTJKhRZGrreYumxY&s=xoOeS1RNOATX4K5WSvEy7WE1VZbB9hXH_f_BWQ_Ea1g&e= 
> 

I don't know how far we are from implementing *a* new (hopefully) better
solution for this, so shall I just go on with the dictionary suggested
above?

You probably did and I probably forgot since then :)

Lastly, you talked about on IRC or in another mail I don't remember that
you would very much see this array in a separate file so that it can be
reused in other parts (and why not in some automation
tests/scripts/builds/whatever) so that we only have to maintain one file
and everything depending on releases and in which state they are, etc..
would be gathered at the same place. I guess we could put this info into
a json file that is then loaded and parsed by the javascript though we
have to make sure the parsing of the JSON is safe, which is another
topic in itself :)

Cheers,
Quentin

Re: [docs] [PATCH 2/4] docs: sphinx-static: switchers.js: correctly highlight obsolete releases

[Michael Opdenacker]

Quentin, Nicolas,

Thanks for the proposals!

On 10/5/21 4:11 PM, Quentin Schulz wrote:
> This is a different topic but yes we should settle on some solution that
> is better than this. We could have a separate git repo somewhere for
> that file. Then I can think of two solutions:
>
> 1) git clone this repo as part of the documentation
>  publishing/development, which is "nicer" because it's explicit the
>  switchers.js is the same for all releases but it's still just a cleaner
>  way to implement the find command above,
>
> 2) have the web server serve this js in a
>  docs.yoctoproject.org/somepath/switchers.js and add this path to the
>  sphinx template, though we would need to think of a way to not need
>  internet access on local development but I'm sure we can think of some
>  hackish way :)


I'd vote for 1), which looks cleaner. The file served by the webserver
would be in a git repository anyway.

>
> Also, I would very much like we have a similar mechanism for the
> theme_override.css for Sphinx because I've fixed a few things in the
> last few months and those aren't shown on old releases.
>
>> I've faced issues when trying to load an 'external' XML file into the
>> docs website (something to deal with proxy or permissions..).. so I
>> tried to have the 'release information' in one structure (in
>> switchers.js as an intermediate step), which looks like that:
>>
>> +  var all_versions = [
>> +    {'version' : 'dev', 'name' : 'dev (3.3)', 'show' : 'yes'},
>> +
>> +    {'version' : '3.2',   'show' : 'yes'},
>> +
>> +    {'version' : '3.1.3', 'show' : 'yes', 'docbook' : 'yes'},
>> +    {'version' : '3.1.2', 'show' : 'yes', 'docbook' : 'yes', 'state'
>> : 'outdated'},
>> +    {'version' : '3.1.1', 'show' : 'yes', 'docbook' : 'yes', 'state'
>> : 'outdated'},
>> +    {'version' : '3.1',   'show' : 'yes', 'docbook' : 'yes', 'state'
>> : 'outdated'},
>> +
>> +    {'version' : '3.0.4', 'show' : 'yes', 'docbook' : 'yes', 'state'
>> : 'obsolete'},
>> +    {'version' : '3.0.3', 'show' : 'no', 'docbook' : 'yes', 'state' :
>> 'obsolete'},
>> +    {'version' : '3.0.2', 'show' : 'no', 'docbook' : 'yes', 'state' :
>> 'obsolete'},
>> +    {'version' : '3.0.1', 'show' : 'no', 'docbook' : 'yes', 'state' :
>> 'obsolete'},
>> +    {'version' : '3.0',   'show' : 'no', 'docbook' : 'yes', 'state' :
>> 'obsolete'},
>> +
>> +    {'version' : '2.7.4', 'show' : 'yes', 'docbook' : 'yes', 'state'
>> : 'obsolete'},
>> +    {'version' : '2.7.3', 'show' : 'no', 'docbook' : 'yes', 'state' :
>> 'obsolete'},
>> +    {'version' : '2.7.2', 'show' : 'no', 'docbook' : 'yes', 'state' :
>> 'obsolete'},
>> +    {'version' : '2.7.1', 'show' : 'no', 'docbook' : 'yes', 'state' :
>> 'obsolete'},
>> +    {'version' : '2.7',   'show' : 'no', 'docbook' : 'yes', 'state' :
>> 'obsolete'},
>> +  ];
>>
>> At least, it becomes straightforward to insert a new release in the
>> table.. I am not sure I ever showed that.. so adding more to the
>> discussion.. I am sure the project would benefit from an overall
>> releases information database in a few other places, so that could be
>> extended.
>>
>>  [1] https://urldefense.proofpoint.com/v2/url?u=http-3A__git.yoctoproject.org_cgit_cgit.cgi_yocto-2Dautobuilder-2Dhelper_tree_scripts_run-2Ddocs-2Dbuild&d=DwIBaQ&c=_sEr5x9kUWhuk4_nFwjJtA&r=LYjLexDn7rXIzVmkNPvw5ymA1XTSqHGq8yBP6m6qZZ4njZguQhZhkI_-172IIy1t&m=IkqJJb6C5WoayEw2QGUj-ZxPis-lTJKhRZGrreYumxY&s=xoOeS1RNOATX4K5WSvEy7WE1VZbB9hXH_f_BWQ_Ea1g&e= 
>>
> I don't know how far we are from implementing *a* new (hopefully) better
> solution for this, so shall I just go on with the dictionary suggested
> above?
>
> You probably did and I probably forgot since then :)
>
> Lastly, you talked about on IRC or in another mail I don't remember that
> you would very much see this array in a separate file so that it can be
> reused in other parts (and why not in some automation
> tests/scripts/builds/whatever) so that we only have to maintain one file
> and everything depending on releases and in which state they are, etc..
> would be gathered at the same place. I guess we could put this info into
> a json file that is then loaded and parsed by the javascript though we
> have to make sure the parsing of the JSON is safe, which is another
> topic in itself :)


By the way, it would also be nice to include the release date and EOL
date (which could be in the past... that's another way of marking a
release as obsolete). This way, we could have the information of whether
a release is obsolete or otherwise until when it will supported, in the
documentation itself and on the release pages too, and not just on a
wiki page.

This would address https://bugzilla.yoctoproject.org/show_bug.cgi?id=14503

Quentin, am I right to assume that we're waiting for further decisions
on this thread before merging your commits? Or do you think we could
already merge some of them?

Thanks again,

Michael.

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

Re: [docs] [PATCH 2/4] docs: sphinx-static: switchers.js: correctly highlight obsolete releases

[Quentin Schulz]

On October 5, 2021 6:29:11 PM GMT+02:00, Michael Opdenacker <michael.opdenacker@bootlin.com> wrote:
>Quentin, Nicolas,
>
>Thanks for the proposals!
>
>On 10/5/21 4:11 PM, Quentin Schulz wrote:
>> This is a different topic but yes we should settle on some solution that
>> is better than this. We could have a separate git repo somewhere for
>> that file. Then I can think of two solutions:
>>
>> 1) git clone this repo as part of the documentation
>>  publishing/development, which is "nicer" because it's explicit the
>>  switchers.js is the same for all releases but it's still just a cleaner
>>  way to implement the find command above,
>>
>> 2) have the web server serve this js in a
>>  docs.yoctoproject.org/somepath/switchers.js and add this path to the
>>  sphinx template, though we would need to think of a way to not need
>>  internet access on local development but I'm sure we can think of some
>>  hackish way :)
>
>
>I'd vote for 1), which looks cleaner. The file served by the webserver
>would be in a git repository anyway.
>

Absolutely, the difference being `git clone` during development or a <script> in the <head> of the docs.yoctoprpject.org pointing to a URL.

>>
>> Also, I would very much like we have a similar mechanism for the
>> theme_override.css for Sphinx because I've fixed a few things in the
>> last few months and those aren't shown on old releases.
>>
>>> I've faced issues when trying to load an 'external' XML file into the
>>> docs website (something to deal with proxy or permissions..).. so I
>>> tried to have the 'release information' in one structure (in
>>> switchers.js as an intermediate step), which looks like that:
>>>
>>> +  var all_versions = [
>>> +    {'version' : 'dev', 'name' : 'dev (3.3)', 'show' : 'yes'},
>>> +
>>> +    {'version' : '3.2',   'show' : 'yes'},
>>> +
>>> +    {'version' : '3.1.3', 'show' : 'yes', 'docbook' : 'yes'},
>>> +    {'version' : '3.1.2', 'show' : 'yes', 'docbook' : 'yes', 'state'
>>> : 'outdated'},
>>> +    {'version' : '3.1.1', 'show' : 'yes', 'docbook' : 'yes', 'state'
>>> : 'outdated'},
>>> +    {'version' : '3.1',   'show' : 'yes', 'docbook' : 'yes', 'state'
>>> : 'outdated'},
>>> +
>>> +    {'version' : '3.0.4', 'show' : 'yes', 'docbook' : 'yes', 'state'
>>> : 'obsolete'},
>>> +    {'version' : '3.0.3', 'show' : 'no', 'docbook' : 'yes', 'state' :
>>> 'obsolete'},
>>> +    {'version' : '3.0.2', 'show' : 'no', 'docbook' : 'yes', 'state' :
>>> 'obsolete'},
>>> +    {'version' : '3.0.1', 'show' : 'no', 'docbook' : 'yes', 'state' :
>>> 'obsolete'},
>>> +    {'version' : '3.0',   'show' : 'no', 'docbook' : 'yes', 'state' :
>>> 'obsolete'},
>>> +
>>> +    {'version' : '2.7.4', 'show' : 'yes', 'docbook' : 'yes', 'state'
>>> : 'obsolete'},
>>> +    {'version' : '2.7.3', 'show' : 'no', 'docbook' : 'yes', 'state' :
>>> 'obsolete'},
>>> +    {'version' : '2.7.2', 'show' : 'no', 'docbook' : 'yes', 'state' :
>>> 'obsolete'},
>>> +    {'version' : '2.7.1', 'show' : 'no', 'docbook' : 'yes', 'state' :
>>> 'obsolete'},
>>> +    {'version' : '2.7',   'show' : 'no', 'docbook' : 'yes', 'state' :
>>> 'obsolete'},
>>> +  ];
>>>
>>> At least, it becomes straightforward to insert a new release in the
>>> table.. I am not sure I ever showed that.. so adding more to the
>>> discussion.. I am sure the project would benefit from an overall
>>> releases information database in a few other places, so that could be
>>> extended.
>>>
>>>  [1] https://urldefense.proofpoint.com/v2/url?u=http-3A__git.yoctoproject.org_cgit_cgit.cgi_yocto-2Dautobuilder-2Dhelper_tree_scripts_run-2Ddocs-2Dbuild&d=DwIBaQ&c=_sEr5x9kUWhuk4_nFwjJtA&r=LYjLexDn7rXIzVmkNPvw5ymA1XTSqHGq8yBP6m6qZZ4njZguQhZhkI_-172IIy1t&m=IkqJJb6C5WoayEw2QGUj-ZxPis-lTJKhRZGrreYumxY&s=xoOeS1RNOATX4K5WSvEy7WE1VZbB9hXH_f_BWQ_Ea1g&e= 
>>>
>> I don't know how far we are from implementing *a* new (hopefully) better
>> solution for this, so shall I just go on with the dictionary suggested
>> above?
>>
>> You probably did and I probably forgot since then :)
>>
>> Lastly, you talked about on IRC or in another mail I don't remember that
>> you would very much see this array in a separate file so that it can be
>> reused in other parts (and why not in some automation
>> tests/scripts/builds/whatever) so that we only have to maintain one file
>> and everything depending on releases and in which state they are, etc..
>> would be gathered at the same place. I guess we could put this info into
>> a json file that is then loaded and parsed by the javascript though we
>> have to make sure the parsing of the JSON is safe, which is another
>> topic in itself :)
>
>
>By the way, it would also be nice to include the release date and EOL
>date (which could be in the past... that's another way of marking a
>release as obsolete). This way, we could have the information of whether
>a release is obsolete or otherwise until when it will supported, in the
>documentation itself and on the release pages too, and not just on a
>wiki page.
>
>This would address https://bugzilla.yoctoproject.org/show_bug.cgi?id=14503
>

That's something we could add later also if needed, just need to add proper keys to the JSON dictionary and not change the current layout so we don't break anything ☺️

>Quentin, am I right to assume that we're waiting for further decisions
>on this thread before merging your commits? Or do you think we could
>already merge some of them?
>

Waiting on feedback and decision on what to do next. No merge yet.

Cheers,
Quentin

>Thanks again,
>
>Michael.
>