From 12add6c6ec92554a7e77623a6a07be5899a71460 Mon Sep 17 00:00:00 2001 From: Felix Moessbauer Date: Mon, 30 Sep 2024 13:43:16 +0200 Subject: [PATCH] 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 Signed-off-by: Jan Kiszka --- .readthedocs.yaml | 11 ++++-- docs/Makefile | 16 ++++++-- docs/_man/kas-container.rst | 24 ++++++++++++ docs/conf.py | 3 ++ docs/userguide.rst | 1 + docs/userguide/kas-container-description.inc | 7 ++++ docs/userguide/kas-container.rst | 12 ++++++ scripts/checkcode.sh | 2 +- scripts/kas-container-usage-to-rst.sh | 41 ++++++++++++++++++++ 9 files changed, 109 insertions(+), 8 deletions(-) create mode 100644 docs/_man/kas-container.rst create mode 100644 docs/userguide/kas-container-description.inc create mode 100644 docs/userguide/kas-container.rst create mode 100755 scripts/kas-container-usage-to-rst.sh diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 0090fafe..a33ac0eb 100644 --- a/.readthedocs.yaml +++ b/.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: diff --git a/docs/Makefile b/docs/Makefile index 5de69c71..d41c38cd 100644 --- a/docs/Makefile +++ b/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." diff --git a/docs/_man/kas-container.rst b/docs/_man/kas-container.rst new file mode 100644 index 00000000..7c2c75ca --- /dev/null +++ b/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 diff --git a/docs/conf.py b/docs/conf.py index f607f6ed..ca8129bd 100644 --- a/docs/conf.py +++ b/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', diff --git a/docs/userguide.rst b/docs/userguide.rst index 1fdd7870..ad6a575c 100644 --- a/docs/userguide.rst +++ b/docs/userguide.rst @@ -9,3 +9,4 @@ User Guide userguide/project-configuration userguide/build-attestation userguide/credentials + userguide/kas-container diff --git a/docs/userguide/kas-container-description.inc b/docs/userguide/kas-container-description.inc new file mode 100644 index 00000000..d660e93d --- /dev/null +++ b/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``. diff --git a/docs/userguide/kas-container.rst b/docs/userguide/kas-container.rst new file mode 100644 index 00000000..0ace45a7 --- /dev/null +++ b/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 diff --git a/scripts/checkcode.sh b/scripts/checkcode.sh index 1b18aae5..c7b5f5ea 100755 --- a/scripts/checkcode.sh +++ b/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 \ diff --git a/scripts/kas-container-usage-to-rst.sh b/scripts/kas-container-usage-to-rst.sh new file mode 100755 index 00000000..7136dd32 --- /dev/null +++ b/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 +# +# 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