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

Hi,

On Wed Jul 8, 2026 at 2:05 PM CEST, Quentin Schulz wrote:
> On 7/8/26 1:58 PM, Antonin Godard wrote:
>> 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?).
>> 
>
> I don't understand why you want to have it in yocto-docs. It would 
> require a user of OE-Core/BitBake to clone the docs to have access to a 
> file that says where to find the documentation of a variable in... the 
> docs... on the Internet.
>
>>>> 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.
>> 
>
> It won't, because you cannot force users to use pre-commit and it's 
> bound to happen someone will forgot to check and merge commits which 
> don't modify the file and add a variable (but yeah, the next person 
> running pre-commit for a commit will bring it back eventually and I'm 
> assuming you would be one of those people :) ).
>
> But maybe.... we don't need to version the result of the script? Just 
> the script itself and if you need whatever this outputs, you run the 
> script whenever you want to and you get data relevant to the current 
> state of your tree?

On one hand, running the script will most likely require Sphinx to run which
requires an extra dependency on the host to run the script. It could be provided
by python3-sphinx-native but that's not ideal (because pulling Python etc.).

On the other hand, maintaining the file in yocto-docs costs nothing. If you
build the docs, generating the file is just an extra step afterwards. Certainly
not everyone will build it, but it will get updated over time. I think leaving
the generation of this file to yocto-docs takes away this responsibility from
the user, and just makes things easier for the user? Especially if we write some
configuration fragment / bitbake-setup mechanism to include it automatically.

Antonin