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

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

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

> And you could probably also adapt it for other 
> things, like documentation for a task since we do have links for each 
> task in the docs. Also qa-checks, etc...

Yes, actually, my branch also covers tasks right now, but QA-checks might be
worth looking into as well.

Thanks!
Antonin