docs: document kas-container command

The kas-container script is the last undocumented tool of the kas suite.
To change this, we add a page in the html documentation and a manpage.

As the kas-container script is written in bash, the sphinx-build
automodule plugin cannot be used to extract the parameters. To work
around this, we run the kas-container script during the docs build,
extract the usage information and massage that a bit to be RST compliant
(and look nice). Then, the generated files are included in the
documentation templates.

As the kas-container docs are generated on the fly, we also must ignore
missing-files errors (D000 Problems with "include" directive path) when
statically checking the doc tree with doc8.

Signed-off-by: Felix Moessbauer <[email protected]>
Signed-off-by: Jan Kiszka <[email protected]>

.readthedocs.yaml

@@ -1,6 +1,6 @@
 # kas - setup tool for bitbake based projects
 #
-# Copyright (c) Siemens AG, 2021
+# Copyright (c) Siemens AG, 2021-2024
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -23,11 +23,16 @@
 version: 2
 
 build:
-  os: ubuntu-20.04
+  os: ubuntu-24.04
   tools:
-    python: "3.9"
+    python: "3.12"
   apt_packages:
     - python3-newt
+    - make
+    - podman
+  jobs:
+    pre_build:
+      - cd docs && make kas-container-usage && cd ..
 
 python:
   install:

docs/Makefile

@@ -49,19 +49,19 @@ clean:
 	rm -rf $(BUILDDIR)/*
 
 .PHONY: html
-html:
+html: kas-container-usage
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
 .PHONY: dirhtml
-dirhtml:
+dirhtml: kas-container-usage
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
 .PHONY: singlehtml
-singlehtml:
+singlehtml: kas-container-usage
 	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
 	@echo
 	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
@@ -154,8 +154,16 @@ text:
 	@echo
 	@echo "Build finished. The text files are in $(BUILDDIR)/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}' \
+	    > $(BUILDDIR)/kas-container-usage-synopsis.inc
+	@../kas-container --help | ../scripts/kas-container-usage-to-rst.sh | awk '/KAS-COMMANDS/ {found=1} found' \
+	    > $(BUILDDIR)/kas-container-usage-options.inc
+
 .PHONY: man
-man:
+man: kas-container-usage
 	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) -t man $(BUILDDIR)/man
 	@echo
 	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."

docs/_man/kas-container.rst

@@ -0,0 +1,24 @@
+:orphan:
+
+kas-container manpage
+=====================
+
+.. include:: ../_build/kas-container-usage-synopsis.inc
+
+DESCRIPTION
+-----------
+
+.. include:: ../userguide/kas-container-description.inc
+
+.. include:: ../_build/kas-container-usage-options.inc
+
+SEE ALSO
+--------
+
+:manpage:`kas(1)`,
+
+.. include:: _kas-man-footer.inc
+
+.. |SYNOPSIS| replace:: SYNOPSIS
+.. |OPTIONS| replace:: OPTIONS
+.. |KAS-COMMANDS| replace:: KAS-CONTAINER COMMANDS

docs/conf.py

@@ -322,6 +322,9 @@
 man_pages = [
     ('_man/kas', 'kas', 'a setup tool for bitbake based projects',
      [author], 1),
+    ('_man/kas-container',
+     'kas-container', 'a setup tool for bitbake based projects',
+     [author], 1),
     ('_man/kas-plugin-build', 'kas-build', 'kas build plugin',
      [author], 1),
     ('_man/kas-plugin-checkout', 'kas-checkout', 'kas checkout plugin',

docs/userguide.rst

@@ -9,3 +9,4 @@ User Guide
   userguide/project-configuration
   userguide/build-attestation
   userguide/credentials
+  userguide/kas-container

docs/userguide/kas-container-description.inc

@@ -0,0 +1,7 @@
+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. The wrapper also takes care of
+mounting the necessary directories and setting up the environment variables.
+
+As container backends, Docker and Podman are supported.
+To force the use of podman over docker, set ``KAS_CONTAINER_ENGINE=podman``.

docs/userguide/kas-container.rst

@@ -0,0 +1,12 @@
+Building in a Container
+=======================
+
+.. include:: kas-container-description.inc
+
+.. include:: ../_build/kas-container-usage-synopsis.inc
+
+.. include:: ../_build/kas-container-usage-options.inc
+
+.. |SYNOPSIS| replace:: Synopsis
+.. |OPTIONS| replace:: Options
+.. |KAS-COMMANDS| replace:: kas-container Commands

scripts/checkcode.sh

@@ -15,7 +15,7 @@ echo "Checking with flake8"
 flake8 "$SRCDIR" || ERROR=$((ERROR + 2))
 
 echo "Checking with doc8"
-doc8  "$SRCDIR"/docs --ignore-path "$SRCDIR"/docs/_build || ERROR=$((ERROR + 4))
+doc8  "$SRCDIR"/docs --ignore-path "$SRCDIR"/docs/_build --ignore D000 || ERROR=$((ERROR + 4))
 
 echo "Checking with shellcheck"
 shellcheck "$SRCDIR"/kas-container \

scripts/kas-container-usage-to-rst.sh

@@ -0,0 +1,41 @@
+#!/bin/sh
+#
+# kas - setup tool for bitbake based projects
+#
+# Copyright (c) Siemens AG, 2024
+#
+# Authors:
+#  Felix Moessbauer <[email protected]>
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+# Extract the usage information of kas-container and convert it to rst
+# to be included in the documentation.
+
+cat - | \
+    sed    's/^Usage:/|SYNOPSIS|\n----------\n/g' | \
+    sed -e 's/^\s*kas-container /| kas-container /g' | \
+    # unwrap long lines
+    perl -0pe 's/\n\s\s+/ /g' | \
+    sed    's/^Positional arguments:/|KAS-COMMANDS|\n--------------/g' | \
+    # each commands starts with a new line
+    sed -r 's/^(build|checkout|dump|shell|for-all-repos|clean|cleansstate|cleanall|menu)\t\t*(.*)$/:\1: \2/g' | \
+    sed    's/^Optional arguments:/|OPTIONS|\n---------/g' | \
+    sed    '/^You can force/d' | \
+    cat