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

Hi Antonin,

On 7/8/26 12:03 PM, Antonin Godard wrote:
> Hi,
> 
> On Mon Jul 6, 2026 at 3:01 PM CEST, Quentin Schulz wrote:
>> Hi Antonin,
>>
>> On 7/3/26 5:07 PM, Antonin Godard via lists.yoctoproject.org wrote:
>>> [I have pushed this here for now:
>>>    https://git.yoctoproject.org/yocto-docs/log/?h=contrib/agodard/b4/gen-doc-links
>>>
>>>    Not sent to mailing list as patches are quite big.]
>>>
>>> The purpose of this series is to make links to yocto-docs accessible
>>> from OE-Core through a doclink flag, making the overall documentation
>>> more accessible. This link can be shown with:
>>>
>>>     $ bitbake-getvar do_install --value -f doclink
>>>     https://docs.yoctoproject.org/blacksail/ref-manual/tasks.html#term-do_install
>>>     $ bitbake-getvar S --value -f doclink
>>>     https://docs.yoctoproject.org/blacksail/ref-manual/variables.html#term-S
>>>
>>> This is made possible through a file generated automatically, which
>>> contains assignments such as:
>>>
>>> S[doclink] = 'https://docs.yoctoproject.org/${LAYERSERIES_COMPAT_core}/ref-manual/variables.html#term-S'
>>> do_install[doclink] = 'https://docs.yoctoproject.org/${LAYERSERIES_COMPAT_core}/ref-manual/tasks.html#term-do_install'
>>>
>>> This can be used in projects that want to point to documentation, like
>>> Toaster.
>>>
>>> This could also be included automatically from OE-Core's bitbake.conf with:
>>>
>>>     # Default path to yocto-docs, assuming it is next to the openembedded-core
>>>     # repository, as would be provided by bitbake-setup.
>>>     YOCTO_DOCS_DIR ??= "${COREBASE}/../yocto-docs"
>>>
>>>     include ${YOCTO_DOCS_DIR}/documentation/oecore/doclinks.conf
>>>
>>> The main point for this is to make documentation for variables easily
>>> accessible, with the hope that this would also encourage people to
>>> contribute to documentation more as it would create a bridge between
>>> OE-Core and yocto-docs.
>>>
>>> This is more of an idea than anything though, comments on whether you
>>> think this would be useful are welcome!
>>>
>>
>> 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.

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

> Anyway, I did a bit of playing with the inventory and I was able to generate the
> same file (doclinks.conf) using it and sphinx.util.inventory's InventoryFile
> class (the one used internally by the intersphinx extension).
> 
>> With this, you don't need to keep
>> updating your docs and be sure it's up to date, you just download what
>> you need (we have objects.inv for each release I believe), you don't
>> need to migrate any docs release as we already have it (Dunfell has one
>> for example). The downside is that if you want to do this locally
>> instead of remotely fetching the file you then need to compile the docs
>> instead of just fetching the source code for the docs. The intersphinx code is
>> in the Sphinx source tree, so we can always adapt it to generate whatever we
>> need if this isn't 100% matching what you want to do.
>>
>> You could even add a link to the bitbake docs as well since we also have
>> an objects.inv for it.
> 
> Good point, I think what might work is make BitBake's variable definitions
> override the ones from yocto-docs, since we generally "document" BitBake
> variables in yocto-docs with "See :term:`bitbake:<var>` in the BitBake manual."
> 

We have done the opposite till now, have OE-Core point at BitBake's if 
it doesn't augment it, otherwise augment it. So I think you'd lose 
information by having BitBake's override yocto-docs's.

Cheers,
Quentin