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

From: Quentin Schulz <foss@0leil.net>
To: docs@lists.yoctoproject.org,
	Michael Opdenacker <michael.opdenacker@bootlin.com>,
	Quentin Schulz <quentin.schulz@theobroma-systems.com>,
	Nicolas Dechesne <nicolas.dechesne@linaro.org>
Cc: YP docs mailing list <docs@lists.yoctoproject.org>
Subject: Re: [docs] [PATCH 2/4] docs: sphinx-static: switchers.js: correctly highlight obsolete releases
Date: Wed, 06 Oct 2021 09:41:14 +0200	[thread overview]
Message-ID: <815A38D5-A8DA-427A-9349-1CFECF22CE14@0leil.net> (raw)
In-Reply-To: <0c6caeec-da66-2bc1-1f6f-6e93c7dd009f@bootlin.com>

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.
>