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

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

Hi,

On Thu Feb 5, 2026 at 2:08 PM CET, Quentin Schulz via lists.yoctoproject.org wrote:
> 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?

Yes, I think I'd like to port these simplifications to yocto-docs soon after,
while memory is still fresh

>> 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 use it in doc/conf.py:

current_version = 'dev'

with open("bitbake.yaml") as data:
    buff = data.read()
    subst_vars = yaml.safe_load(buff)
    current_version = subst_vars["DOCCONF_VERSION"]

So basically we just need a way to pass this information from set_versions.py to
the sphinx-build command.

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

So basically, you'd write a variables.py file from set_versions.py and read it
from conf.py?

I'm starting to wonder if it just wouldn't be better do move all of this logic
into doc/conf.py, actually.

Thanks,
Antonin