docs: docgen proto with protoc-gen-doc

.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

docgen/proto/.gitignore

@@ -0,0 +1 @@
+/docs/

docgen/proto/gen.sh

@@ -0,0 +1,41 @@
+#!/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"
+  title="CycloneDX v$version Proto Reference"
+  echo "Generating: $title"
+
+  ## 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=/templates/html.tmpl,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