[PATCH v2 0/3] More docs fixes

[Jan Kiszka]

Minor cleanups.

v2 as it replaces https://groups.google.com/g/kas-devel/c/VuFzJCpCTnI.

Jan

Jan Kiszka (3):
docs: Fold kas-container-description.inc into kas-container.rst
docs: Fix long line
scripts: Add .inc files to doc8 check

docs/command-line/environment-variables.inc | 3 +-
docs/userguide/kas-container-description.inc | 45 ------------------
docs/userguide/kas-container.rst | 50 +++++++++++++++++++-
scripts/checkcode.sh | 2 +-
4 files changed, 52 insertions(+), 48 deletions(-)
delete mode 100644 docs/userguide/kas-container-description.inc

--
2.47.3

[Jan Kiszka]

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

Missed so far as the checker ignored .inc.

Signed-off-by: Jan Kiszka <jan.k...@siemens.com>
---
docs/command-line/environment-variables.inc | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/command-line/environment-variables.inc b/docs/command-line/environment-variables.inc
index ef4c0bf..0f01d98 100644
--- a/docs/command-line/environment-variables.inc
+++ b/docs/command-line/environment-variables.inc
@@ -246,7 +246,8 @@ overwritten using the ``env`` section of the config file.
.. |aws_cred| replace:: ``AWS_ROLE_ARN``
``AWS_SHARED_CREDENTIALS_FILE``
``AWS_WEB_IDENTITY_TOKEN_FILE``
-.. |git_cred| replace:: ``GIT_CREDENTIAL_HELPER`` ``GIT_CREDENTIAL_USEHTTPPATH``
+.. |git_cred| replace:: ``GIT_CREDENTIAL_HELPER``
+ ``GIT_CREDENTIAL_USEHTTPPATH``
.. |kas_git_cred_store| replace:: ``KAS_GIT_CREDENTIAL_STORE``
.. |kas_git_cred_socket| replace:: ``KAS_GIT_CREDENTIAL_SOCKET``
.. |ci_server_vars| replace:: ``CI_SERVER_HOST``
--
2.47.3

[Jan Kiszka]

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

No content changes, just no longer needed.

As now the style checker bites, we need to reformat long lines, though.

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

docs/userguide/kas-container-description.inc | 45 ------------------
docs/userguide/kas-container.rst | 50 +++++++++++++++++++-

2 files changed, 49 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..00769a2 100644
--- a/docs/userguide/kas-container.rst
+++ b/docs/userguide/kas-container.rst
@@ -1,4 +1,52 @@
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

[Jan Kiszka]

Less minor cleanups. More an attempt the make command line documenation
easier to find. Pleaes have a look at the result at

https://kas.readthedocs.io/en/next/index.html

This appears more consistent to me at least.

v3 also supersedes https://groups.google.com/g/kas-devel/c/GTBmZZP3yPk.

Jan

Jan Kiszka (4):
docs: Fix long lines

scripts: Add .inc files to doc8 check

docs: Fold Command Line Usage section into User Guide
kas: Drop useless subparser help string

docs/_man/kas.rst | 2 +-
docs/command-line.rst | 15 ------
docs/index.rst | 1 -
docs/userguide.rst | 2 +
docs/userguide/cmdline.rst | 8 +++
docs/userguide/env-vars.rst | 6 +++
.../environment-variables.inc | 3 +-
docs/userguide/kas-container-description.inc | 53 ++++++++++---------
kas/kas.py | 2 +-
scripts/checkcode.sh | 2 +-
10 files changed, 50 insertions(+), 44 deletions(-)
delete mode 100644 docs/command-line.rst
create mode 100644 docs/userguide/cmdline.rst
create mode 100644 docs/userguide/env-vars.rst
rename docs/{command-line => userguide}/environment-variables.inc (99%)

--
2.47.3