gendocs: generate image ENV var documentation

gendocs.py is a rudimentary Python script that operates on the output of
a cekit build (including a dry-run) and generates AsciiDoc
Environment-variable documentation for the image.

gendocs.sh is a harness to invoke gendocs.py for every image and version
we care about: it switches to different git branches and tags, collects
the image descriptors and runs gendocs.py.

Add a GitHub workflow to invoke gendocs.sh and upload the results to
GitHub Pages. Trigger on pushes to the ubi8 or ubi9 branches, or a tag
matching the pattern for releases.

Signed-off-by: Jonathan Dowland <[email protected]>

Author: jmtd

.github/workflows/gendocs.yml

@@ -0,0 +1,53 @@
+name: Generate docs for OpenJDK images
+on:
+  push:
+    branches:
+    - 'ubi8'
+    - 'ubi9'
+    - 'gendocs'
+    tags:
+    - 'ubi?-openjdk-containers*'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  gendocs:
+    name: Generate documentation
+    runs-on: ubuntu-20.04
+    strategy:
+      fail-fast: false
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          fetch-depth: 0 # all branches and tags
+
+      - name: Install CEKit
+        uses: cekit/[email protected]
+
+      - name: Setup required packages for docs
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y asciidoctor
+
+      - name: Generate docs
+        run: |
+          ./gendocs.sh
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: 'docs'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

docs/README.adoc

@@ -0,0 +1,17 @@
+# Red Hat UBI OpenJDK container images
+
+This is auto-generated documentation for the
+link:https://www.redhat.com/en/blog/introducing-red-hat-universal-base-image[Red
+Hat Universal Base Image] (UBI) OpenJDK container images.
+
+* link:https://github.com/jboss-container-images/openjdk[container image source repository]
+
+Container images are available from the
+link:https://catalog.redhat.com/software/containers/explore[Red Hat Ecosystem
+Catalog].
+
+The documentation lists the environment variables that are available for
+configuring the behavior of the images.
+
+Documentation is available for the development branches (UBI8, UBI9) and all
+tagged releases.

gendocs.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+
+# read in all the module YAML files specified for an image, in order, to
+# produce a comprehensive list of configuration environment variables,
+# then write them out to something useful
+
+import yaml
+import sys
+
+def getvars():
+    y = yaml.safe_load(open("target/image.yaml","r"))
+    es = {}
+
+    for mobj in y['modules']['install']:
+        mname = mobj['name']
+        mf = open("target/image/modules/{}/module.yaml".format(mname))
+        my = yaml.safe_load(mf)
+        for h in my['envs']:
+            es[h['name']] = h
+
+    es2 = list(es.values())
+    es2.sort(key=(lambda h: h['name']))
+    return es2
+
+def adocpreamble(title):
+    print("= {}".format(title))
+    print("Jonathan Dowland <[email protected]>")
+    print(":toc:")
+    print()
+
+def adoctable(es,ty,test, field):
+    print("== {} variables".format(ty))
+    print(".Table {} variables".format(ty))
+    print("|===")
+    print("|Name |{}{} |Description".format(field[0].upper(),field[1:]))
+    for h in es:
+        if test(h):
+            print("|{}".format(h['name']))
+            print("|`{}`".format(h.get(field,'-')))
+            print("|{}".format(h.get('description','-')))
+    print("|===")
+    print()
+
+def main(title):
+    es = getvars()
+    adocpreamble(title)
+    adoctable(es,"Informational",lambda h: 'value' in h, 'value')
+    adoctable(es,"Configuration",lambda h: 'value' not in h, 'example')
+
+if __name__ == "__main__":
+    main(sys.argv[1])

gendocs.sh

@@ -0,0 +1,82 @@
+#!/bin/bash
+set -euo pipefail
+
+# This script arranges to call gendocs.py for each image descriptor we
+# wish to generate documentation for, by switching to the relevant git
+# branches and tags and enumerating the image descriptors.
+# It is expected that this script is invoked via GitHub Actions.
+
+engine=${engine-podman}
+
+die()
+{
+    echo "$@"
+    exit 1
+}
+
+addToIndex()
+{
+    echo -e "$@" >> "$workdir/README.adoc"
+}
+
+# generate docs for a single image
+genImageDocs()
+{
+    ref="$1"   # e.g. ubi8
+    input="$2" # e.g. ubi8-openjdk-11.yaml
+
+    name="$(awk '-F"' '/name: &name/ { print $2 }' "$input")"
+    output="docs/$ref/${input/yaml/adoc}"
+
+    mkdir -p "$(dirname "$output")"
+    cekit --descriptor "$input" build --dry-run "$engine"
+    python3 "$workdir/gendocs.py" "$name" > "$output"
+    asciidoctor "$output"
+
+    addToIndex "* link:$ref/${name/\//-}.html[$name]"
+}
+
+# moves to the git ref, enumerates all images, calls
+# genImageDocs for each
+handleRef()
+{
+    ref="$1"
+    git checkout "$ref"
+    for y in ubi?-*yaml; do
+        genImageDocs "$ref" "$y"
+    done
+}
+
+##############################################################################
+
+for dep in cekit python3 asciidoctor; do
+    if ! which "$dep" >/dev/null; then
+        die "$dep is required to execute this script"
+    fi
+done
+
+# This ensures the directory won't be purged when we switch refs
+mkdir -p docs
+touch docs/index.html
+
+# backup files from this ref we need prior to switching git refs
+# (we don't bother with cleaning up workdir, GHA will do that for us)
+workdir="$(mktemp -td gendocs.XXXXXX)"
+cp ./gendocs.py "$workdir/gendocs.py"
+cp ./docs/README.adoc "$workdir/README.adoc"
+
+# documentation for development branches
+addToIndex "\n== Development branches ==\n"
+for branch in ubi8 ubi9; do
+    addToIndex "\n=== $branch ===\n"
+    handleRef "$branch" "$branch"
+done
+
+# documentation for tagged releases
+addToIndex "\n== Released images =="
+for tag in $(git tag -l 'ubi?-openjdk-containers*' | sort -r); do
+    addToIndex "\n=== $tag ===\n"
+    handleRef "$tag"
+done
+
+asciidoctor "$workdir/README.adoc" -o docs/index.html