Re: [docs] [PATCH v2 26/56] ref-manual/structure.rst: remove obsolete poky repo references

[Quentin Schulz <quentin.schulz@cherry.de>]

Hi Antonin,

On 1/27/26 9:19 AM, Antonin Godard via lists.yoctoproject.org wrote:
> Remove references to the Poky repository, replace by OpenEmbedded-Core
> in most cases.
> 
> Add a introductory directory layout at the top that is reflected in the
> following section. This document no longer uses Poky as its source
> directory, so all paths are explicitly mentioned, to highlight the
> separation between core components. This lead to some re-organization of
> some sections.
> 
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
>   documentation/bsp-guide/bsp.rst        |   4 +-
>   documentation/ref-manual/structure.rst | 169 ++++++++++++++++++++-------------
>   documentation/ref-manual/terms.rst     |   2 +-
>   3 files changed, 105 insertions(+), 70 deletions(-)
> 
> diff --git a/documentation/bsp-guide/bsp.rst b/documentation/bsp-guide/bsp.rst
> index 4c0939ab0..67f61b7b2 100644
> --- a/documentation/bsp-guide/bsp.rst
> +++ b/documentation/bsp-guide/bsp.rst
> @@ -81,7 +81,7 @@ directory of that Layer. This directory is what you add to the
>   ``conf/bblayers.conf`` file found in your
>   :term:`Build Directory`, which is
>   established after you run the OpenEmbedded build environment setup
> -script (i.e. :ref:`ref-manual/structure:``oe-init-build-env```).
> +script (i.e. :ref:`structure-core-script`).
>   Adding the root directory allows the :term:`OpenEmbedded Build System`
>   to recognize the BSP
>   layer and from it build an image. Here is an example::
> @@ -221,7 +221,7 @@ section.
>         Checking connectivity... done.
>   
>   #. *Initialize the Build Environment:* While in the :term:`Source Directory`,
> -run the :ref:`ref-manual/structure:``oe-init-build-env``` environment setup
> +run the :ref:`structure-core-script` environment setup
>   script located in :term:`OpenEmbedded-Core (OE-Core)` to define the OpenEmbedded
>   build environment on your build host. ::
>   
> diff --git a/documentation/ref-manual/structure.rst b/documentation/ref-manual/structure.rst
> index d567cade0..86f3109e1 100644
> --- a/documentation/ref-manual/structure.rst
> +++ b/documentation/ref-manual/structure.rst
> @@ -16,6 +16,19 @@ and directories.
>      names that contain spaces. Be sure that the Source Directory you use
>      does not contain these types of names.
>   
> +For the following sections, we assume the core components of the :term:`Source
> +Directory` are organized as follows:
> +
> +.. code-block:: text
> +
> +   ├── build/
> +   │   └── ...
> +   └── layers/
> +       ├── bitbake/
> +       ├── meta-yocto/
> +       ├── openembedded-core/
> +       └── yocto-docs/
> +
>   .. _structure-core:
>   
>   Top-Level Core Components
> @@ -67,8 +80,8 @@ about the contents of the :term:`Build Directory`.
>   
>   .. _handbook:
>   
> -``documentation/``
> -------------------
> +``layers/yocto-docs/``
> +----------------------
>   

suggestion:

+The Yocto documentation repository is hosted at
+:yocto_git:`/yocto-docs`.


>   This directory holds the source for the Yocto Project documentation as
>   well as templates and tools that allow you to generate PDF and HTML
> @@ -76,37 +89,28 @@ versions of the manuals. Each manual is contained in its own sub-folder;
>   for example, the files for this reference manual reside in the
>   ``ref-manual/`` directory.
>   
> +This directory is not mandatory for building with :term:`BitBake`.
> +
> +``layers/openembedded-core/``
> +-----------------------------
> +
> +The :term:`OpenEmbedded-Core (OE-Core)` repository is hosted at
> +:oe_git:`/openembedded-core`.
> +
>   .. _structure-core-meta:
>   
> -``meta/``
> ----------
> +``layers/openembedded-core/meta/``
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>   
>   This directory contains the minimal, underlying OpenEmbedded-Core

suggestion: :term:`OpenEmbedded-Core (OE-Core)`

>   metadata. The directory holds recipes, common classes, and machine
>   configuration for strictly emulated targets (``qemux86``, ``qemuarm``,
>   and so forth.)
>   
> -.. _structure-core-meta-poky:
> -
> -``meta-poky/``
> ---------------
> -
> -Designed above the ``meta/`` content, this directory adds just enough
> -metadata to define the Poky reference distribution.
> -
> -.. _structure-core-meta-yocto-bsp:
> -
> -``meta-yocto-bsp/``
> --------------------
> -
> -This directory contains the Yocto Project reference hardware Board
> -Support Packages (BSPs). For more information on BSPs, see the
> -:doc:`/bsp-guide/index`.
> -
>   .. _structure-meta-selftest:
>   
> -``meta-selftest/``
> -------------------
> +``layers/openembedded-core/meta-selftest/``
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>   
>   This directory adds additional recipes and append files used by the
>   OpenEmbedded selftests to verify the behavior of the build system. You
> @@ -115,15 +119,15 @@ want to run the selftests.
>   
>   .. _structure-meta-skeleton:
>   
> -``meta-skeleton/``
> -------------------
> +``layers/openembedded-core/meta-skeleton/``
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>   
>   This directory contains template recipes for BSP and kernel development.
>   
>   .. _structure-core-scripts:
>   
> -``scripts/``
> -------------
> +``layers/openembedded-core/scripts/``
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>   
>   This directory contains various integration scripts that implement extra
>   functionality in the Yocto Project environment (e.g. QEMU scripts). The
> @@ -136,8 +140,8 @@ back to the Yocto Project, such as ``create-pull-request`` and
>   
>   .. _structure-core-script:
>   
> -``oe-init-build-env``
> ----------------------
> +``layers/openembedded-core/oe-init-build-env``
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For this one and all the others (above and below): watch out, this will 
switch the cross-reference default string from oe-init-build-env to 
layers/openembedded-core/oe-init-build-env, is this what we want? Do we 
need to change the cross-reference string everywhere?

[...]

Cheers,
Quentin