[PATCH] doc: Fold kas-container-description.inc into kas-container.rst

[Jan Kiszka]

From: Jan Kiszka <jan.k...@siemens.com>

No content changes, just no longer needed.

Signed-off-by: Jan Kiszka <jan.k...@siemens.com>
---

Depends on https://groups.google.com/g/kas-devel/c/GTBmZZP3yPk

docs/userguide/kas-container-description.inc | 45 -------------------
docs/userguide/kas-container.rst | 46 +++++++++++++++++++-
2 files changed, 45 insertions(+), 46 deletions(-)
delete mode 100644 docs/userguide/kas-container-description.inc

diff --git a/docs/userguide/kas-container-description.inc b/docs/userguide/kas-container-description.inc
deleted file mode 100644
index 7789a5f..0000000
--- a/docs/userguide/kas-container-description.inc
+++ /dev/null
@@ -1,45 +0,0 @@
-The ``kas-container`` script is a wrapper to run `kas` inside a build container.
-It gives fine grained control over the data that is mapped into the build and
-decouples the build environment from the host system. For details, see
-:ref:`kas-container-label` and :ref:`env-vars-label`. The wrapper also
-takes care of mounting the necessary directories and setting up the environment
-variables inside the container.
-
-.. note::
- The ``kas-container`` script has limited support for Git worktrees. Regular
- Git operations on the checked-out repository are supported. However, executing
- any ``git worktree ...`` command inside the container is not allowed.
-
-By default ``kas-container`` uses the official images provided by the kas project:
-``ghcr.io/siemens/kas/kas[-isar]:<version>``. To specify your own image set the
-``KAS_CONTAINER_IMAGE`` environment variable. The ``kas-container`` script version
-should match the kas version inside the container. If kas detects that is was called
-from ``kas-container`` and the versions do not match, a warning is emitted. This
-limitation might be lessened in the future, once a stable interface between
-``kas-container`` and kas is introduced.
-
-From version ``5.0`` onward, kas offers images built on several base
-distributions. Select a distribution by setting the environment variable
-``KAS_CONTAINER_IMAGE_DISTRO`` to the desired value (e.g. ``debian-bookworm``
-or ``debian-trixie``). The corresponding image tags follow the pattern
-``:<version>-<base-distro>`` (e.g. ``:5.0-debian-bookworm``).
-Alternatively, you can adjust ``KAS_CONTAINER_IMAGE_DISTRO_DEFAULT`` in the
-``kas-container`` script if you copy this into your downstream layer already
-for encoding the supported kas version.
-
-As container backends, Docker and
-Podman are supported. To force the use of podman over docker, set
-``KAS_CONTAINER_ENGINE=podman``. For details, see :ref:`env-vars-label`.
-
-Running under docker in `rootless mode <https://docs.docker.com/engine/security/rootless/>`_
-is partially supported. It is recommended to use a distinct ``KAS_WORK_DIR`` outside of the
-calling directory (repo-dir), as kas temporarily changes the ownership of the working
-directory during its operation. All files managed by kas (including the repos) must not be
-written to from the host. To completely remove all data managed by kas, use
-``kas-container purge``. This also restores the directory owners of the dirs passed to kas,
-so they can be removed from the host.
-
-.. note::
- The ISAR build system is compatible with rootless execution in ``isar-rootless``
- mode only. The ``isar`` and ``isar-privileged`` modes fall back to the system docker
- or podman instance.
diff --git a/docs/userguide/kas-container.rst b/docs/userguide/kas-container.rst
index d51ec82..be57917 100644
--- a/docs/userguide/kas-container.rst
+++ b/docs/userguide/kas-container.rst
@@ -1,4 +1,48 @@
Building in a Container
=======================

-.. include:: kas-container-description.inc
+The ``kas-container`` script is a wrapper to run `kas` inside a build container.
+It gives fine grained control over the data that is mapped into the build and
+decouples the build environment from the host system. For details, see
+:ref:`kas-container-label` and :ref:`env-vars-label`. The wrapper also
+takes care of mounting the necessary directories and setting up the environment
+variables inside the container.
+
+.. note::
+ The ``kas-container`` script has limited support for Git worktrees. Regular
+ Git operations on the checked-out repository are supported. However, executing
+ any ``git worktree ...`` command inside the container is not allowed.
+
+By default ``kas-container`` uses the official images provided by the kas project:
+``ghcr.io/siemens/kas/kas[-isar]:<version>``. To specify your own image set the
+``KAS_CONTAINER_IMAGE`` environment variable. The ``kas-container`` script version
+should match the kas version inside the container. If kas detects that is was called
+from ``kas-container`` and the versions do not match, a warning is emitted. This
+limitation might be lessened in the future, once a stable interface between
+``kas-container`` and kas is introduced.
+
+From version ``5.0`` onward, kas offers images built on several base
+distributions. Select a distribution by setting the environment variable
+``KAS_CONTAINER_IMAGE_DISTRO`` to the desired value (e.g. ``debian-bookworm``
+or ``debian-trixie``). The corresponding image tags follow the pattern
+``:<version>-<base-distro>`` (e.g. ``:5.0-debian-bookworm``).
+Alternatively, you can adjust ``KAS_CONTAINER_IMAGE_DISTRO_DEFAULT`` in the
+``kas-container`` script if you copy this into your downstream layer already
+for encoding the supported kas version.
+
+As container backends, Docker and
+Podman are supported. To force the use of podman over docker, set
+``KAS_CONTAINER_ENGINE=podman``. For details, see :ref:`env-vars-label`.
+
+Running under docker in `rootless mode <https://docs.docker.com/engine/security/rootless/>`_
+is partially supported. It is recommended to use a distinct ``KAS_WORK_DIR`` outside of the
+calling directory (repo-dir), as kas temporarily changes the ownership of the working
+directory during its operation. All files managed by kas (including the repos) must not be
+written to from the host. To completely remove all data managed by kas, use
+``kas-container purge``. This also restores the directory owners of the dirs passed to kas,
+so they can be removed from the host.
+
+.. note::
+ The ISAR build system is compatible with rootless execution in ``isar-rootless``
+ mode only. The ``isar`` and ``isar-privileged`` modes fall back to the system docker
+ or podman instance.
--
2.47.3