[PATCH 1/2] docs: Fail kas-container doc generation on error

[Felix Moessbauer]

We directly copy the synopsis of the kas-container script into the docs
by calling the script with --help and then processing the result.
However, when the script cannot be called the error is not propagated
which results in incorrect or no synopsis data being written to the
docs.

We fix this by ensuring that the Makefile target fails on error, using
pipefail.

Fixes: 12add6c6e ("docs: document kas-container command")
Signed-off-by: Felix Moessbauer <felix.mo...@siemens.com>
---
docs/Makefile | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index d41c38cd7..2292e68eb 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -157,9 +157,9 @@ text:
kas-container-usage:
@echo Generate kas-container usage documentation
@mkdir -p $(BUILDDIR)
- @../kas-container --help | ../scripts/kas-container-usage-to-rst.sh | awk '/KAS-COMMANDS/ {exit} {print}' \
+ @set -o pipefail; ../kas-container --help | ../scripts/kas-container-usage-to-rst.sh | awk '/KAS-COMMANDS/ {exit} {print}' \
> $(BUILDDIR)/kas-container-usage-synopsis.inc
- @../kas-container --help | ../scripts/kas-container-usage-to-rst.sh | awk '/KAS-COMMANDS/ {found=1} found' \
+ @set -o pipefail; ../kas-container --help | ../scripts/kas-container-usage-to-rst.sh | awk '/KAS-COMMANDS/ {found=1} found' \
> $(BUILDDIR)/kas-container-usage-options.inc

.PHONY: man
--
2.53.0

[Felix Moessbauer]

Even if pre-conditions for a proper kas-container invocation are not met
(e.g. no container runtime), we must be able to print the usage /
synopsis. Otherwise the documentation generator depends on fulfilling
all pre-conditions for invoking kas in a container.

Avoiding this dependency is especially relevant for distro packaging,
where having a container engine should not be a pre-condition of building
the kas package.

Fixes: 12add6c6e ("docs: document kas-container command")
Signed-off-by: Felix Moessbauer <felix.mo...@siemens.com>
---

kas-container | 10 +++++++---
1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/kas-container b/kas-container
index 8e4937d9c..f0d9d82bc 100755
--- a/kas-container
+++ b/kas-container
@@ -324,6 +324,13 @@ setup_kas_dirs()
}
setup_kas_dirs

+# Allow --help to work without a container engine or other pre-condition checks
+for _arg in "$@"; do
+ case "$_arg" in
+ -h|--help) usage 0 ;;
+ esac
+done
+
KAS_CONTAINER_ENGINE="${KAS_CONTAINER_ENGINE:-${KAS_DOCKER_ENGINE}}"
if [ -z "${KAS_CONTAINER_ENGINE}" ]; then
# Try to auto-detect a container engine
@@ -442,9 +449,6 @@ while [ $# -gt 0 ]; do
echo "${KAS_CONTAINER_SELF_NAME} $KAS_IMAGE_VERSION_DEFAULT"
exit 0
;;
- -h | --help)
- usage 0
- ;;
--*)
usage
;;
--
2.53.0

[Jan Kiszka]

On 31.05.26 18:17, Felix Moessbauer wrote:
> We directly copy the synopsis of the kas-container script into the docs
> by calling the script with --help and then processing the result.
> However, when the script cannot be called the error is not propagated
> which results in incorrect or no synopsis data being written to the
> docs.
>
> We fix this by ensuring that the Makefile target fails on error, using
> pipefail.

You briefly made me nervous that we created broken docs with th 5.3. But
this patch is purely defensive, addressing potentially incomplete local
setups, right?

>
> Fixes: 12add6c6e ("docs: document kas-container command")
> Signed-off-by: Felix Moessbauer <felix.mo...@siemens.com>
> ---
> docs/Makefile | 4 ++--
> 1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/docs/Makefile b/docs/Makefile
> index d41c38cd7..2292e68eb 100644
> --- a/docs/Makefile
> +++ b/docs/Makefile
> @@ -157,9 +157,9 @@ text:
> kas-container-usage:
> @echo Generate kas-container usage documentation
> @mkdir -p $(BUILDDIR)
> - @../kas-container --help | ../scripts/kas-container-usage-to-rst.sh | awk '/KAS-COMMANDS/ {exit} {print}' \
> + @set -o pipefail; ../kas-container --help | ../scripts/kas-container-usage-to-rst.sh | awk '/KAS-COMMANDS/ {exit} {print}' \
> > $(BUILDDIR)/kas-container-usage-synopsis.inc
> - @../kas-container --help | ../scripts/kas-container-usage-to-rst.sh | awk '/KAS-COMMANDS/ {found=1} found' \
> + @set -o pipefail; ../kas-container --help | ../scripts/kas-container-usage-to-rst.sh | awk '/KAS-COMMANDS/ {found=1} found' \
> > $(BUILDDIR)/kas-container-usage-options.inc
>
> .PHONY: man

Jan

--
Siemens AG, Foundational Technologies
Linux Expert Center

[Jan Kiszka]

On 31.05.26 18:17, Felix Moessbauer wrote:

I would pull that even further up. usage() is already callable right
after its definition, no further init needed.

Jan

> KAS_CONTAINER_ENGINE="${KAS_CONTAINER_ENGINE:-${KAS_DOCKER_ENGINE}}"
> if [ -z "${KAS_CONTAINER_ENGINE}" ]; then
> # Try to auto-detect a container engine
> @@ -442,9 +449,6 @@ while [ $# -gt 0 ]; do
> echo "${KAS_CONTAINER_SELF_NAME} $KAS_IMAGE_VERSION_DEFAULT"
> exit 0
> ;;
> - -h | --help)
> - usage 0
> - ;;
> --*)
> usage
> ;;

--

[MOESSBAUER, Felix]

On Sun, 2026-05-31 at 19:54 +0200, Jan Kiszka wrote:
> On 31.05.26 18:17, Felix Moessbauer wrote:
> > We directly copy the synopsis of the kas-container script into the docs
> > by calling the script with --help and then processing the result.
> > However, when the script cannot be called the error is not propagated
> > which results in incorrect or no synopsis data being written to the
> > docs.
> >
> > We fix this by ensuring that the Makefile target fails on error, using
> > pipefail.
>
> You briefly made me nervous that we created broken docs with th 5.3. But
> this patch is purely defensive, addressing potentially incomplete local
> setups, right?

It's not a 5.3 bug, but much older. At least the docs on RTD are
correct (check for Synopsis in [1]). I spotted this while checking the
packaging in Debian - which has broken docs (only the manpage for kas-
container is incomplete), but this was broken ever since we added a
manpage for kas-container, because neither podman nor docker is (and
should be) a build dependency.

[1] https://kas.readthedocs.io/en/latest/userguide/kas-container.html

Felix

[Felix Moessbauer]

We directly copy the synopsis of the kas-container script into the docs
by calling the script with --help and then processing the result.
However, when the script cannot be called the error is not propagated
which results in incorrect or no synopsis data being written to the

docs. This finally results in a missing synopsis of kas-container, both
in the manpage and the html docs. No other documentation parts are
affected.

We fix this by ensuring that the Makefile target fails on error, using
pipefail.

Fixes: 12add6c6e ("docs: document kas-container command")
Signed-off-by: Felix Moessbauer <felix.mo...@siemens.com>
---

Changes since v1:
- Improve commit message to make clear it only affects the docs
of kas-container

docs/Makefile | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index d41c38cd7..2292e68eb 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -157,9 +157,9 @@ text:
kas-container-usage:
@echo Generate kas-container usage documentation
@mkdir -p $(BUILDDIR)
- @../kas-container --help | ../scripts/kas-container-usage-to-rst.sh | awk '/KAS-COMMANDS/ {exit} {print}' \
+ @set -o pipefail; ../kas-container --help | ../scripts/kas-container-usage-to-rst.sh | awk '/KAS-COMMANDS/ {exit} {print}' \
> $(BUILDDIR)/kas-container-usage-synopsis.inc
- @../kas-container --help | ../scripts/kas-container-usage-to-rst.sh | awk '/KAS-COMMANDS/ {found=1} found' \
+ @set -o pipefail; ../kas-container --help | ../scripts/kas-container-usage-to-rst.sh | awk '/KAS-COMMANDS/ {found=1} found' \
> $(BUILDDIR)/kas-container-usage-options.inc

.PHONY: man

--
2.53.0

[Felix Moessbauer]

Even if pre-conditions for a proper kas-container invocation are not met
(e.g. no container runtime), we must be able to print the usage /
synopsis. Otherwise the documentation generator depends on fulfilling
all pre-conditions for invoking kas in a container.

Avoiding this dependency is especially relevant for distro packaging,
where having a container engine should not be a pre-condition of building
the kas package.

Fixes: 12add6c6e ("docs: document kas-container command")
Signed-off-by: Felix Moessbauer <felix.mo...@siemens.com>
---
Changes since v1:

- move the processing of --help right after the usage definition

kas-container | 10 +++++++---
1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/kas-container b/kas-container

index 8e4937d9c..1feba4bb7 100755
--- a/kas-container
+++ b/kas-container
@@ -101,6 +101,13 @@ usage()
exit "${EXIT_CODE:-1}"

}

+# Allow --help to work without a container engine or other pre-condition checks
+for _arg in "$@"; do
+ case "$_arg" in
+ -h|--help) usage 0 ;;
+ esac
+done
+

fatal_error()
{
echo "${KAS_CONTAINER_SELF_NAME}: Error: $*" >&2

@@ -442,9 +449,6 @@ while [ $# -gt 0 ]; do
echo "${KAS_CONTAINER_SELF_NAME} $KAS_IMAGE_VERSION_DEFAULT"
exit 0
;;
- -h | --help)
- usage 0
- ;;
--*)
usage
;;
--

2.53.0

[Jan Kiszka]

I kept the original indention.

> + esac
> +done
> +
> fatal_error()
> {
> echo "${KAS_CONTAINER_SELF_NAME}: Error: $*" >&2
> @@ -442,9 +449,6 @@ while [ $# -gt 0 ]; do
> echo "${KAS_CONTAINER_SELF_NAME} $KAS_IMAGE_VERSION_DEFAULT"
> exit 0
> ;;
> - -h | --help)
> - usage 0
> - ;;
> --*)
> usage
> ;;

Thanks, both applied with that minor style change.

[Jan Kiszka]

On 01.06.26 07:39, Felix Moessbauer wrote:

Seems there is a small but critical difference in the RTD build env:

https://app.readthedocs.org/projects/kas/builds/32929662/

[MOESSBAUER, Felix]

Argh... pipefail is bash only. It might be better to move the whole
processing to a sphinx plugin (similar to how we process the schema)
and avoid the pipes altogether.

Please anyways apply p2 as this carries the relevant fix. I'll rework
p1 and move it to a sphinx plugin, but this might take some time.

Felix

[Jan Kiszka]

OK, dropped this patch from next now.

[Jan Kiszka]

Dropping patch 2 again - it breaks "kas-container <plugin> --help".

We need to address the root cause of the issue instead, ie. move the
container detection after command line parsing. Let me write a patch...

[MOESSBAUER, Felix]

Indeed, for this help message we need to start the container. I'll add
a couple of CI tests for both cases. This code is tricky.

Felix