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

[Quentin Schulz <quentin.schulz@cherry.de>]

Hi Antonin,

On 2/5/26 12:34 PM, Antonin Godard wrote:
> Hi,
> 
> On Wed Feb 4, 2026 at 4:01 PM CET, Quentin Schulz via lists.yoctoproject.org wrote:
> [...]
>>> +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 :))
> 

Yeah set_versions.py and the switchers aren't the nicest things to dig 
into :/

Is the above mechanism something we could migrate yp-docs switcher to to 
simplify it a bit?

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

The benefit of having a .in file is that it's explicit what the user can 
use in the docs (if we have yocto-vars.py! which we don't (yet?) in 
BitBake).

What's the usecase for DOCCONF_VERSION BTW? We only use it for setting 
the current version (always "dev") but we never override it? Either in 
release branches, in the autobuilder, only from set_versions.py do we 
read it and override it. But then it's nowhere to be found in the docs 
either so we don't use. Do we actually need this for BitBake?

We could push this even further if we wanted to and have a bitbake.py 
instead? In some internal Sphinx project, we provide a skeleton with 
options to provide (Python) variables through another file we then include:

exec(open('variables.py').read())

is what we use. This would support f-strings (can easily reference a 
variable from another one), multiline strings, etc. No need to parse 
anything, it just needs to be valid Python variable assignment.

Cheers,
Quentin