From 55dc0efdefbb5c5de5f9c181a6b37a706836f10a Mon Sep 17 00:00:00 2001
From: Jan Kowalleck <jan.kowalleck@gmail.com>
Date: Sun, 29 Dec 2024 16:28:53 +0100
Subject: [PATCH] docs: docgen proto with `protoc-gen-doc`

Signed-off-by: Jan Kowalleck <jan.kowalleck@gmail.com>
---
 .github/workflows/build_docs.yml | 18 +++++++++++++++
 docgen/proto/.gitignore          |  1 +
 docgen/proto/gen.sh              | 39 ++++++++++++++++++++++++++++++++
 3 files changed, 58 insertions(+)
 create mode 100644 docgen/proto/.gitignore
 create mode 100755 docgen/proto/gen.sh

diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml
index 2d0b41e9..492a8e9d 100644
--- a/.github/workflows/build_docs.yml
+++ b/.github/workflows/build_docs.yml
@@ -59,3 +59,21 @@ jobs:
         name: JSON-Schema-documentation
         path: docgen/json/docs
         if-no-files-found: error
+  docs_proto:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docgen/proto
+    steps:
+    - name: Checkout
+      # see https://github.com/actions/checkout
+      uses: actions/checkout@v4
+    - name: Generate Schema documentation
+      run: ./gen.sh
+    - name: Archive Schema documentation
+      # https://github.com/actions/upload-artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: PROTO-Schema-documentation
+        path: docgen/proto/docs
+        if-no-files-found: error
diff --git a/docgen/proto/.gitignore b/docgen/proto/.gitignore
new file mode 100644
index 00000000..6e684992
--- /dev/null
+++ b/docgen/proto/.gitignore
@@ -0,0 +1 @@
+/docs/
diff --git a/docgen/proto/gen.sh b/docgen/proto/gen.sh
new file mode 100755
index 00000000..1e940c1c
--- /dev/null
+++ b/docgen/proto/gen.sh
@@ -0,0 +1,39 @@
+#!/bin/bash
+set -eu
+
+THIS_PATH="$(realpath "$(dirname "$0")")"
+SCHEMA_PATH="$(realpath "$THIS_PATH/../../schema")"
+DOCS_PATH="$THIS_PATH/docs"
+TEMPLATES_PATH="$THIS_PATH/templates"
+
+PROTOC_GEN_DOC_VERSION='1.5.1'
+
+# --
+
+rm -f -R "$DOCS_PATH"
+mkdir -p "$DOCS_PATH/"{1.3,1.4,1.5,1.6}
+
+generate () {
+  version="$1"
+
+  ## docs: https://github.com/pseudomuto/protoc-gen-doc
+  docker run --rm \
+    -v "${DOCS_PATH}/${version}:/out" \
+    -v "${SCHEMA_PATH}:/protos:ro" \
+    -v "${TEMPLATES_PATH}:/templates:ro" \
+    "pseudomuto/protoc-gen-doc:${PROTOC_GEN_DOC_VERSION}" \
+      --doc_opt=html,index.html \
+      "bom-${version}.proto"
+
+  # fix file permissions
+  docker run --rm \
+    -v "${DOCS_PATH}/${version}:/out" \
+    --entrypoint chown \
+    "pseudomuto/protoc-gen-doc:${PROTOC_GEN_DOC_VERSION}" \
+    "$(id -g):$(id -u)" -R /out
+}
+
+generate 1.3
+generate 1.4
+generate 1.5
+generate 1.6