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

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

Cheers,
Quentin