Merge remote-tracking branch 'origin/master' into 1.7-dev

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/json/gen.sh

@@ -7,7 +7,6 @@ DOCS_PATH="$THIS_PATH/docs"
 TEMPLATES_PATH="$THIS_PATH/templates"
 
 rm -f -R "$DOCS_PATH"
-mkdir -p "$DOCS_PATH/"{1.2,1.3,1.4,1.5,1.6,1.7}
 
 # Check to see if generate-schema-doc is executable and is in the path. If not, install JSON Schema for Humans.
 if ! [ -x "$(command -v generate-schema-doc)" ]
@@ -27,7 +26,10 @@ generate () {
   then
       SCHEMA_FILE="$STRICT_SCHEMA_FILE"
   fi
-  echo "$SCHEMA_FILE"
+  echo "SCHEMA_FILE: $SCHEMA_FILE"
+
+  OUT_FILE="$DOCS_PATH/$version/json/index.html"
+  mkdir -p "$(dirname "$OUT_FILE")"
 
   generate-schema-doc \
     --config no_link_to_reused_ref \
@@ -38,11 +40,11 @@ generate () {
     --config custom_template_path="$TEMPLATES_PATH/cyclonedx/base.html" \
     --minify \
     "$SCHEMA_FILE" \
-    "$DOCS_PATH/$version/index.html"
+    "$OUT_FILE"
 
-  sed -i -e "s/\${quotedTitle}/\"$title\"/g" "$DOCS_PATH/$version/index.html"
-  sed -i -e "s/\${title}/$title/g" "$DOCS_PATH/$version/index.html"
-  sed -i -e "s/\${version}/$version/g" "$DOCS_PATH/$version/index.html"
+  sed -i -e "s/\${quotedTitle}/\"$title\"/g" "$OUT_FILE"
+  sed -i -e "s/\${title}/$title/g" "$OUT_FILE"
+  sed -i -e "s/\${version}/$version/g" "$OUT_FILE"
 }
 
 generate 1.2

docgen/json/templates/cyclonedx/base.html

@@ -55,6 +55,11 @@
                     <li><a class="dropdown-item" href="/docs/1.2/xml/">v1.2 (XML)</a></li>
                     <li><a class="dropdown-item" href="/docs/1.1/xml/">v1.1 (XML)</a></li>
                     <li><a class="dropdown-item" href="/docs/1.0/xml/">v1.0 (XML)</a></li>
+                    <li><hr class="dropdown-divider"/></li>
+                    <li><a class="dropdown-item" href="/docs/1.6/proto/">v1.6 (Protobuf)</a></li>
+                    <li><a class="dropdown-item" href="/docs/1.5/proto/">v1.5 (Protobuf)</a></li>
+                    <li><a class="dropdown-item" href="/docs/1.4/proto/">v1.4 (Protobuf)</a></li>
+                    <li><a class="dropdown-item" href="/docs/1.3/proto/">v1.3 (Protobuf)</a></li>
                 </ul>
             </li>
         </ul>

docgen/proto/.gitignore

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

docgen/proto/gen.sh

@@ -0,0 +1,48 @@
+#!/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 Protobuf Reference"
+  echo "Generating: $title"
+
+  OUT_DIR="$DOCS_PATH/$version/proto"
+  OUT_FILE="index.html"
+  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,"$OUT_FILE" \
+      "bom-${version}.proto"
+
+  # fix file permissions
+  docker run --rm \
+    -v "${OUT_DIR}:/out" \
+    --entrypoint chown \
+    "pseudomuto/protoc-gen-doc:${PROTOC_GEN_DOC_VERSION}" \
+    "$(id -u):$(id -g)" -R /out
+
+  sed -i -e "s/\${quotedTitle}/\"$title\"/g" "$OUT_DIR/$OUT_FILE"
+  sed -i -e "s/\${title}/$title/g" "$OUT_DIR/$OUT_FILE"
+  sed -i -e "s/\${version}/$version/g" "$OUT_DIR/$OUT_FILE"
+}
+
+generate 1.3
+generate 1.4
+generate 1.5
+generate 1.6