Re: [docs] [PATCH v2] doc: fix the switchers menu

["Antonin Godard" <antonin.godard@bootlin.com>]

Hi,

On Wed Feb 4, 2026 at 4:01 PM CET, Quentin Schulz via lists.yoctoproject.org wrote:
[...]
>> diff --git a/doc/set_versions.py b/doc/set_versions.py
>> new file mode 100755
>> index 00000000000..63fba2fe948
>> --- /dev/null
>> +++ b/doc/set_versions.py
>> @@ -0,0 +1,155 @@
>> +#!/usr/bin/env python3
>> +#
>> +# This is a minimal version of the set_versions.py from yocto-docs,
>> +# use to replace VERSIONS_PLACEHOLDER in switchers.js.in by a list defined below
>> +# with BITBAKE_ACTIVE_RELEASES in the environment.
>> +#
>
> Where?

A leftover from the previous version, thanks.

[...]
>> +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 "VERSIONS_PLACEHOLDER" in line:
>> +            if ourversion != "dev":
>> +                w.write(f"    'dev': 'Unstable (dev)',\n")
>> +            for series in activereleases:
>> +                w.write(f"    '{series}': '{series} ({yocto_mapping[series]})',\n")
>
> Why is this different from yp-docs? We don't handle showing the current 
> series (ourseries)/version (ourversion) if it's outdated anymore?

We do, but from switchers.js, where in build_version_select we push the current
version of the document last:

    buf.push(
      '<option value="' +
        current_version +
        '" selected="selected">' +
        current_title +
        "</option>",
    );

So the version from our branch gets displayed.

(trust me, I've had a hard time locating and understanding how all of this
worked :))

However, you made me realize that due to our branch the abbrev hash, it would
always appear as outdated. I fixed that for v2.

> To answer Richard on the other thread, we use YAML because JSON doesn't 
> allow comments. Also, because we used to want multiline variables (see 
> https://yaml-multiline.info/) which aren't supported in JSON, but those 
> are gone since 8d993022c2ae ("docs: use literalinclude for system 
> requirements"). Not sure we can get rid of it for yp-docs as we only 
> override *some* variables in this file by set_versions.py so the 
> autobuilder won't replace poky.yaml.in, and the YAML is consumed by 
> sphinx/yocto-vars.py.
>
> If we don't plan on having comments in this file *ever*, then the YAML 
> dependency isn't necessary.
>
> Another option is INI and use configparser, c.f. 
> https://docs.python.org/3/library/configparser.html
>
> It seems that INI supports the ':' as key-value delimiter as well as 
> multiline strings (but not the way we used it for YAML!), so it could be 
> a drop-in replacement. We could even simply write to the file with 
> configparser.write() (though that will drop the in-file comments).

If we directly write the ini file with configparser.write(), maybe we can just
maintain the list of variable as Python instead, instead of a separate ".in"
file?

Antonin