docs: docgen proto with protoc-gen-doc (#557)

fixes #555

utilizes https://github.com/pseudomuto/protoc-gen-doc
to generate the needed docs ready to upload to the homepage.

> [!NOTE]
> did not setup a proper template, yet. used the default one for now, so
we can track template-related changes in future PRs
> But the template has been foreseen, it is expected to go into the
folder `docgen/proto/template`.
> See template docs here:
<https://github.com/pseudomuto/protoc-gen-doc/wiki/Custom-Templates>

CI run:
https://github.com/CycloneDX/specification/actions/runs/12536710058/job/34960006706

CI result:
https://github.com/CycloneDX/specification/actions/runs/12536710058/artifacts/2369477602

structure: 
```text
docgen/proto/docs
├── 1.3
│   └── index.html
├── 1.4
│   └── index.html
├── 1.5
│   └── index.html
└── 1.6
    └── index.html
```

----

might rework the resutling structure in regards to
#568

---------

Signed-off-by: Jan Kowalleck <jan.kowalleck@gmail.com>

Author: jkowalleck

.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,43 @@
+#!/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"
+
+generate () {
+  version="$1"
+  title="CycloneDX v$version Proto Reference"
+  echo "Generating: $title"
+
+  OUT_DIR="$DOCS_PATH/$version/proto/"
+  mkdir -p "$OUT_DIR"
+
+  ## docs: https://github.com/pseudomuto/protoc-gen-doc
+  docker run --rm \
+    -v "${OUT_DIR}:/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 "${OUT_DIR}:/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