Re: [docs][PATCH 2/2] ref-manual/classes.rst: add diagram for classes used by base.bbclass

["Antonin Godard" <antonin.godard@bootlin.com>]

On Sun Sep 21, 2025 at 6:43 PM CEST, BELHADJ SALEM Talel via lists.yoctoproject.org wrote:
> The diagram is created using draw.io, I used it also
> to create the BitBake Tasks Map, and I was informed by
> Michael back then to use Inkscape, but I was not successful
> learning it, and that led to me postponing lot of
> contributions. So, I thought contributing draw.io SVGs
> is better than nothing, one day I will fix them with
> Inkscape.

> Signed-off-by: Talel BELHAJ SALEM <bhstalel@gmail.com>
> ---
>  documentation/ref-manual/classes.rst           |   7 +++++++
>  .../figures/base_bbclass_inherits.png          | Bin 0 -> 168001 bytes
>  .../ref-manual/svg/base_bbclass_inherits.svg   |   4 ++++
>  3 files changed, 11 insertions(+)
>  create mode 100644 documentation/ref-manual/figures/base_bbclass_inherits.png
>  create mode 100644 documentation/ref-manual/svg/base_bbclass_inherits.svg
>
> diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
> index 791c6b2ef..703ad98dc 100644
> --- a/documentation/ref-manual/classes.rst
> +++ b/documentation/ref-manual/classes.rst
> @@ -191,6 +191,13 @@ The following actions, among others, are handled by this class:
>  - Handle the provided license via :term:`LICENSE` and :term:`LIC_FILES_CHKSUM` variables
>  - Prepare the native recipe that correspond to the scheme set in :term:`SRC_URI`
>  
> +Besides that, the :ref:`ref-classes-base` class inherits more classes to provide more
> +utilities, set up toolchain variables, add more tasks, and more. The following diagram
> +shows how :ref:`ref-classes-base` is related to other classes:
> +
> +.. image:: figures/base_bbclass_inherits.png

Other places that use SVGs make the following call:

  .. image:: svg/base_bbclass_inherits.*
     :width: 100%

Can you use that instead? It will render the file as non-pixelated in the html
page, which is nicer.

> +   :align: center

Some comments on the diagram:

- I think it's great, it shows what you described in the the line above, i.e.
  the graph of inheritance.

- I'm not sure representing the classes-global/ and classes/ directories add
  much to the diagram. In fact, I would remove the directories here and just
  represent the inheritance between classes.

- This class can evolve over time, and maybe more classes will be inherited in
  the future. So I don't think we need to be exhaustive here. Instead I would do
  something like:

  base.bbclass --------------------> patch.bbclass
                inherit          |-> staging.bbclass
                                 |-> mirrors.bbclass
                                 |-> utils.bbclass
                                 |-> utility-tasks.bbclass
                                 |-> logging.bbclass
                                 \-> ...

  This is just to give the idea of including the "..." at the end. Users can read
  the file if they want the exaustive list.

- I would not include the terminal.bbclass inherit. Classes can include other
  classes but I think the main point of this diagram is to show the basic
  inherits of the base class.

- I like the TOOLCHAIN/TOOLCHAIN_NATIVE mention.

>  .. _ref-classes-bash-completion:
>  
>  ``bash-completion``
> diff --git a/documentation/ref-manual/figures/base_bbclass_inherits.png b/documentation/ref-manual/figures/base_bbclass_inherits.png

No need to include the PNG here. SVGs are automatically converted to PNGs.

[...]
> diff --git a/documentation/ref-manual/svg/base_bbclass_inherits.svg b/documentation/ref-manual/svg/base_bbclass_inherits.svg
> new file mode 100644
> index 000000000..f223eb4d1
> --- /dev/null
> +++ b/documentation/ref-manual/svg/base_bbclass_inherits.svg
> @@ -0,0 +1,4 @@
> +<?xml version="1.0" encoding="UTF-8"?>
> +<!-- Do not edit this file with editors other than draw.io -->

Hmm... if we really can't open that with Inkscape that's a problem from
maintenance :/ I tried opening it with inkscape and indeed, I can't edit the
text and so on. Maybe there's an option in draw.io for exporting for other
editors? Otherwise sadly we can't merge this, as we wouldn't be able to
maintain it easily.

Thanks,
Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com