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

Paul Barker <[email protected]> Mon, 06 Jul 2026 11:02:26 +0100
Newsgroups	org.yoctoproject.lists.docs
Message-ID	<[email protected]>
On Fri, 2026-07-03 at 17:07 +0200, 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!
> 
> Signed-off-by: Antonin Godard <[email protected]>

Hi Antonin,

I think the idea is good! A couple of comments...

I don't think we can set YOCTO_DOCS_DIR by default as there are many
ways of setting up the source layers without cloning the docs repo. We
would need a way to set this in toolcfg.conf via bitbake-setup when the
chosen configuration includes yocto-docs. Then the include directive in
bitbake.conf should be conditional on YOCTO_DOCS_DIR being set.

Also looking at the gen-doc-links script, we should not use a Creative
Commons license for scripts. We should use MIT or GPL.

Best regards,

-- 
Paul Barker
signature.asc (application/pgp-signature, 252 B)