Human-readable specification of Tracing Policy API

(still a draft version: I want to see again how this renders with
Netlify in deploy preview)

This commit includes initial markdown documentation for the
Tracing Policy API, which was generated by OpenAPI Generator.
It is intended as 4th "tile" in the reference section of the
Tetragon online documentation.

HUGO_VERSION was bumped from 0.111.3 to the current version 0.124.1
because Hugo includes an embedded link render hook to resolve
Markdown link destinations, which serves here, since 0.123.0.

fixes #2074

Signed-off-by: Christian Hörtnagl <[email protected]>

contrib/openapi-generator/generate.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+set -e
+trap 'echo "error: $0:$LINENO"' ERR
+
+[ $# -eq 1 ]
+input_spec=$1
+
+output_dir=$(dirname $0)/../../docs/content/en/docs/reference
+[ -f $output_dir/_index.md ]
+
+[ -n "$OPENAPI_GENERATOR_HOME" ]
+
+# curr. using names with underlines, because Markdown link destinations
+# must not use fragment identifiers with spaces
+java -jar $OPENAPI_GENERATOR_HOME/modules/openapi-generator-cli/target/openapi-generator-cli.jar generate -g markdown \
+  -i $input_spec -o $output_dir \
+  --operation-id-name-mappings \
+"createCiliumIoV1alpha1NamespacedTracingPolicyNamespaced=Create_namespaced_tracing_policy",\
+"createCiliumIoV1alpha1TracingPolicy=Create_tracing_policy",\
+"deleteCiliumIoV1alpha1CollectionNamespacedTracingPolicyNamespaced=Delete_collection_of_namespaced_tracing_policies",\
+"deleteCiliumIoV1alpha1CollectionTracingPolicy=Delete_collection_of_tracing_policies",\
+"deleteCiliumIoV1alpha1NamespacedTracingPolicyNamespaced=Delete_namespaced_tracing_policy",\
+"deleteCiliumIoV1alpha1TracingPolicy=Delete_tracing_policy",\
+"listCiliumIoV1alpha1NamespacedTracingPolicyNamespaced=List_namespaced_tracing_policies",\
+"listCiliumIoV1alpha1TracingPolicy=List_tracing_policies",\
+"listCiliumIoV1alpha1TracingPolicyNamespacedForAllNamespaces=List_namespaced_tracing_policies_for_all_namespaces",\
+"patchCiliumIoV1alpha1NamespacedTracingPolicyNamespaced=Patch_namespaced_tracing_policy",\
+"patchCiliumIoV1alpha1TracingPolicy=Patch_tracing_policy",\
+"replaceCiliumIoV1alpha1NamespacedTracingPolicyNamespaced=Replace_namespaced_tracing_policy",\
+"replaceCiliumIoV1alpha1TracingPolicy=Replace_tracing_policy"
+
+# add Hugo front matter as in surrounding content
+cat > $output_dir/tracing-policy-api.md << EOF
+---
+title: Tracing Policy API
+description: This reference is generated from an OpenAPI specification.
+weight: 4
+---
+
+EOF
+cat $output_dir/README.md >> $output_dir/tracing-policy-api.md
+rm $output_dir/README.md
+
+# some more post-processing of generated Markdown
+sed -Ei \
+  's/^# Documentation .+$/# Documentation for Tracing Policy API/;
+  s/^All URIs are relative to .*$//;
+  s/^\| Class (\| Method \| HTTP request \| Description \|)$/\1/;
+  s/^\|------------ .+$/\| --- \| --- \| --- \|/;
+  s/^(\| )?\*CiliumIoV1alpha1Api\* (\| .*)$/\2/;
+  s/^(\|.+\|.+\|).+$/\1/' \
+  $output_dir/tracing-policy-api.md

docs/Dockerfile.hugo

@@ -1,5 +1,5 @@
 FROM curlimages/curl:8.00.1@sha256:9e886c104cae1072f7874c9c214f77c6758f2e8a477234e32eda5fcbfa41f225 AS downloader
-ARG HUGO_VERSION=0.111.3
+ARG HUGO_VERSION=0.124.1
 ARG TARGETARCH
 WORKDIR tmp
 RUN curl -L https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-${TARGETARCH}.tar.gz | tar xz

docs/content/en/docs/reference/.gitignore

@@ -0,0 +1,5 @@
+/.openapi-generator-ignore
+/.openapi-generator/
+/Apis/
+/Models/
+/tracing-policy-api.md

netlify.toml

@@ -22,4 +22,4 @@ command = "npm ci && hugo"
 ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF ."
 
 [build.environment]
-HUGO_VERSION = "0.120.4"
+HUGO_VERSION = "0.124.1"