Re: [docs] [PATCH RFC 0/6] Generate documentation links for OE-Core (cover letter only)

Hi,

On Wed Jul 8, 2026 at 12:24 PM CEST, Quentin Schulz via lists.yoctoproject.org wrote:
[...]
>>> I've barely looked at it but the first question I had when looking at
>>> this was "why a file per variable in the glossary?" and the few commits
>>> I had a look at in the RFC branch don't really say. I think you may have
>>> wanted to generate a list of variables that are in the glossary and
>>> parsing Sphinx is a bit overkill, so just looking for files in a
>>> specific directory would be easier? There are three issues with this
>>> logic, first, we would need to do this for older releases which is
>>> time-consuming and error-prone (I guess you probably wrote a script to
>>> do it, so maybe not that much), second, it may become outdated, third,
>>> you need access to the docs locally.
>>>
>>> Have you considering simply getting the objects.inv file generated by
>>> Sphinx and available at docs.yoctoproject.org/objects.inv?
>>>
>>> python -m sphinx.ext.intersphinx https://docs.yoctoproject.org/objects.inv
>>>
>>> will give you something interesting.
>> 
>> It looks like a great fit for this indeed. My only concern is that this
>> is built after running a Sphinx build. So depending on this file to generate a
>> configuration file that we maintain in yocto-docs means we depend on building
>> the documentation to generate a source file. This is fine, but originally I had
>
> But the neat part is, you can download this file from the official docs 
> so you don't have to build it yourself or require a local copy of the 
> tree like this RFC suggests.

The script could always take an URL as argument and do the fetch part, if we
want to do that out of yocto-docs (but do we, really?).

>> a pre-commit hook that would check whether this doclinks.conf would require
>> updating, and now this hook would require the documentation to be built to run.
>> 
>
> Ah, I did misunderstand the intent here. I somehow thought doclinks.conf 
> was supposed to be part of OE-Core, but I think it would be more 
> appropriate this way, don't you think? We can always provide the script 
> to generate such file, in case someone wants to generate something based 
> on it (like I could imagine some VSCode/vim/emacs plugin that allows a 
> click on the variable and open the doc link in a browser or something). 
> I'm not sure what's the usecase for third party projects to be able to 
> do it though, it'll point to the official docs, where we only document 
> variables in OE-Core/BitBake (and maybe other first-party layers, don't 
> know).

The advantage of keeping this file in yocto-docs is that it can be automatically
updated as we add or remove documentation. I'd say that's nice considering that
variables get added or removed quite a lot. If we maintain that in OE-Core, it
means it would have to be updated regularly through patches, which I think is
not ideal.

Antonin