[v3] doc/bitbake-user-manual-ref-variables: improve INHERIT

Current wording makes it difficult to understand what
exactly is done with INHERIT-ed anonymous functions and
when.

Signed-off-by: Adam Blank <adam.blank.g@gmail.com>
Reviewed-by: Antonin Godard <antonin.godard@bootlin.com>
---
Changes in v2:
- Added reference to Parsing The Base Configuration Metadata
- Emphasised how disjoint the cases are
Changes in v3:
- Regenerate the patch previously corrupted by Emacs

---
 .../bitbake-user-manual-ref-variables.rst         | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)

On Mon Oct 6, 2025 at 8:19 PM CEST, Adam Blank wrote:
> Current wording makes it difficult to understand what
> exactly is done with INHERIT-ed anonymous functions and
> when.
>
> Signed-off-by: Adam Blank <adam.blank.g@gmail.com>
> Reviewed-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
> Changes in v2:
> - Added reference to Parsing The Base Configuration Metadata
> - Emphasised how disjoint the cases are
> Changes in v3:
> - Regenerate the patch previously corrupted by Emacs
>
> ---
>  .../bitbake-user-manual-ref-variables.rst         | 15 ++++++++++++---
>  1 file changed, 12 insertions(+), 3 deletions(-)
>
> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
> index 810f88689..06d48dd47 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
> @@ -1200,9 +1200,18 @@ overview of their function and contents.
>
>     :term:`INHERIT`
>        Causes the named class or classes to be inherited globally. Anonymous
> -      functions in the class or classes are not executed for the base
> -      configuration and in each individual recipe. The OpenEmbedded build
> -      system ignores changes to :term:`INHERIT` in individual recipes.
> +      functions in the class or classes are executed in two disjoint situations:
> +
> +      - When only the
> +	:ref:`base configuration <bitbake-user-manual/bitbake-user-manual-execution:parsing the base configuration metadata>`
> +	is parsed as a result of the following BitBake invocation::
> +
> +	  $ bitbake -e

I guess this is _one_ of the situations where this can happen. Maybe, rephrase
to:

"""
... is parsed. For example, as a result of the following BitBake invocation::
"""

> +
> +      - When recipes are parsed - then for each parsed recipe.
> +
> +      The OpenEmbedded build system ignores changes to :term:`INHERIT`
> +      in individual recipes.

This is the Bitbake documentation and Bitbake is not only used by the
OpenEmbedded build system, so we can't have OpenEmbedded references here. So you
could rephrase to:

"""
BitBake ignores changes to ...
"""

Otherwise some documentation syntax nitpicks, not important but for next time
you will know :) :

* We put two spaces after the "-", like so:

  """
  -  one
  -  two
  """

* We indent code blocks with three spaces usually, like so:

  """
  Here is a code block::

     code
  """

See https://git.yoctoproject.org/yocto-docs/tree/documentation/standards.md. We
try to follow those.

Thanks!
Antonin

Right, thanks for the tips :) I've sent a V4 of this patch.
On a side note, would it make sense to chase other references to
OpenEmbedded in BitBake's documentation?

Thanks,
Adam

On Wed, 8 Oct 2025 at 11:15, Antonin Godard <antonin.godard@bootlin.com>
wrote:

> On Mon Oct 6, 2025 at 8:19 PM CEST, Adam Blank wrote:
> > Current wording makes it difficult to understand what
> > exactly is done with INHERIT-ed anonymous functions and
> > when.
> >
> > Signed-off-by: Adam Blank <adam.blank.g@gmail.com>
> > Reviewed-by: Antonin Godard <antonin.godard@bootlin.com>
> > ---
> > Changes in v2:
> > - Added reference to Parsing The Base Configuration Metadata
> > - Emphasised how disjoint the cases are
> > Changes in v3:
> > - Regenerate the patch previously corrupted by Emacs
> >
> > ---
> >  .../bitbake-user-manual-ref-variables.rst         | 15 ++++++++++++---
> >  1 file changed, 12 insertions(+), 3 deletions(-)
> >
> > diff --git
> a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
> b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
> > index 810f88689..06d48dd47 100644
> > --- a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
> > +++ b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
> > @@ -1200,9 +1200,18 @@ overview of their function and contents.
> >
> >     :term:`INHERIT`
> >        Causes the named class or classes to be inherited globally.
> Anonymous
> > -      functions in the class or classes are not executed for the base
> > -      configuration and in each individual recipe. The OpenEmbedded
> build
> > -      system ignores changes to :term:`INHERIT` in individual recipes.
> > +      functions in the class or classes are executed in two disjoint
> situations:
> > +
> > +      - When only the
> > +     :ref:`base configuration
> <bitbake-user-manual/bitbake-user-manual-execution:parsing the base
> configuration metadata>`
> > +     is parsed as a result of the following BitBake invocation::
> > +
> > +       $ bitbake -e
>
> I guess this is _one_ of the situations where this can happen. Maybe,
> rephrase
> to:
>
> """
> ... is parsed. For example, as a result of the following BitBake
> invocation::
> """
>
> > +
> > +      - When recipes are parsed - then for each parsed recipe.
> > +
> > +      The OpenEmbedded build system ignores changes to :term:`INHERIT`
> > +      in individual recipes.
>
> This is the Bitbake documentation and Bitbake is not only used by the
> OpenEmbedded build system, so we can't have OpenEmbedded references here.
> So you
> could rephrase to:
>
> """
> BitBake ignores changes to ...
> """
>
> Otherwise some documentation syntax nitpicks, not important but for next
> time
> you will know :) :
>
> * We put two spaces after the "-", like so:
>
>   """
>   -  one
>   -  two
>   """
>
> * We indent code blocks with three spaces usually, like so:
>
>   """
>   Here is a code block::
>
>      code
>   """
>
> See
> https://git.yoctoproject.org/yocto-docs/tree/documentation/standards.md.
> We
> try to follow those.
>
> Thanks!
> Antonin
>
> --
> Antonin Godard, Bootlin
> Embedded Linux and Kernel engineering
> https://bootlin.com
>
>

On Wed Oct 8, 2025 at 12:40 PM CEST, Adam Blank via lists.openembedded.org wrote:
> Right, thanks for the tips :) I've sent a V4 of this patch.
> On a side note, would it make sense to chase other references to
> OpenEmbedded in BitBake's documentation?

I don't think it's _that_ important for existing references, unless someone
comes out and complains about it.

If you are looking for ways to contribute, there a list of bugs we try to fix
here: https://wiki.yoctoproject.org/wiki/Newcomers#Newcomer_Bugs

Some of them are docs-related

Thanks!
Antonin