Docs/docsgen one version only (#587)

jkowalleck · web-flow · commit 6374e6f33406 · 2025-02-05T10:04:47.000+01:00
Allow the docs generators to run for a certain version. Previously, they always ran for all in series. --- > original from #507 from @Nicolas-Peiffer The JSON Schema HTML viewer generator script `docgen/json/gen.sh` supports generating only for one particular CycloneDX version, including the possibility of generating the HTML only for draft version of CycloneDX during dev time. ## Use Case I want to propose new objects in the CycloneDX Specification. And for checking the JSON Schema, I like to locally use the HTML view to check the content of the JSON Schema. However, during dev time when I was modifying the JSON Schema, I found it not convenient that the script `docgen/json/gen.sh` regenerate the HTML doc for every version of CycloneDX each time I run it when I only need the version I am working on. ## Proposition I modified the script `docgen/json/gen.sh` to be able to run `gen.sh` only for a particular version of CycloneDX. For example: ```bash ./gen.sh 1.6 ``` But I also added a list `DRAFT_CYCLONEDX_VERSIONS` for when I am working on a draft proposition of CycloneDX spec. For example: ```bash # I modify `docgen/json/gen.sh` to add the name of my draft file DRAFT_CYCLONEDX_VERSIONS=(my_cdx_dev_draft) ``` I create a JSON schema draft file `schema/bom-my_cdx_dev_draft.schema.json`: Then I run: ```bash ./gen.sh my_cdx_dev_draft ``` Which creates only the HTML for `my_cdx_dev_draft` ```bash tree docgen/json/docs/my_cdx_dev_draft/ docgen/json/docs/my_cdx_dev_draft/ ├── index.html ├── schema_doc.css └── schema_doc.min.j ``` And in order not to disturb the way `docgen/json/gen.sh` works now, running it without argument generates the HTML for all the CDX versions: ```bash ./gen.sh ``` ```bash ls -1 docgen/json/docs/ 1.2 1.3 1.4 1.5 1.6 ``` I also added a small usage help message. ```bash ./gen.sh -h Deleting folder /home/thedetective/Documents/dev-workspace/cyclonedx/cyclonedx-specification.thalesgroup/docgen/json/docs Usage: Generate HTML JSON Schema navigator for CyccloneDX Usage: ./gen.sh <version> : runs only for <version> ./gen.sh : loops over all valid and draft CycloneDX versions ``` ## What about `docgen/xml/gen.sh` ? I will probably propose the same kind of modification to the XML `docgen/xml/gen.sh` script to achieve the same results. ## Conclusion There are probably other way to achieve this result. I think this one is the cheapest in terms of how the `gen.sh` script is modified. ---- supersedes #507 closes #507
diff --git a/docgen/json/gen.sh b/docgen/json/gen.sh
@@ -1,35 +1,60 @@
 #!/bin/bash
 set -eu
 
+declare -a CDX_VERSIONS=(
+  '1.6'
+  '1.5'
+  '1.4'
+  '1.3'
+  '1.2'
+)
+
+# region help
+DESC="Generate HTML Schema navigator for CycloneDX JSON"
+USAGE="
+Usage: $0 [CDX_VERSION...]
+
+Supported values for CDX_VERSION: ${CDX_VERSIONS[*]}
+"
+# endregion help
+
+
 THIS_PATH="$(realpath "$(dirname "$0")")"
 SCHEMA_PATH="$(realpath "$THIS_PATH/../../schema")"
 DOCS_PATH="$THIS_PATH/docs"
 TEMPLATES_PATH="$THIS_PATH/templates"
 
-rm -f -R "$DOCS_PATH"
 
-# 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)" ]
-then
-  # dependencies managed externally, so dependebot/renovate can pick it up
-  pip3 install -r "$THIS_PATH/requirements.txt"
-fi
+# --
+
+prepare () {
+  # 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)" ]
+  then
+    # dependencies managed externally, so dependebot/renovate can pick it up
+    python -m pip install -r "$THIS_PATH/requirements.txt"
+  fi
+}
+
 
 generate () {
-  version="$1"
-  title="CycloneDX v${version} JSON Reference"
+  local version="$1"
+  local title="CycloneDX v${version} JSON Reference"
   echo "Generating: $title"
 
-  SCHEMA_FILE="$SCHEMA_PATH/bom-${version}.schema.json"
-  STRICT_SCHEMA_FILE="$SCHEMA_PATH/bom-${version}-strict.schema.json"
+  local SCHEMA_FILE="$SCHEMA_PATH/bom-${version}.schema.json"
+  local STRICT_SCHEMA_FILE="$SCHEMA_PATH/bom-${version}-strict.schema.json"
   if [ -f "$STRICT_SCHEMA_FILE" ]
   then
       SCHEMA_FILE="$STRICT_SCHEMA_FILE"
   fi
   echo "SCHEMA_FILE: $SCHEMA_FILE"
 
-  OUT_FILE="$DOCS_PATH/$version/json/index.html"
-  mkdir -p "$(dirname "$OUT_FILE")"
+  local OUT_FILE="$DOCS_PATH/$version/json/index.html"
+  local OUT_DIR="$(dirname "$OUT_FILE")"
+  rm -rf "$OUT_DIR"
+  mkdir -p "$OUT_DIR"
 
   generate-schema-doc \
     --config no_link_to_reused_ref \
@@ -47,8 +72,42 @@ generate () {
   sed -i -e "s/\${version}/$version/g" "$OUT_FILE"
 }
 
-generate 1.2
-generate 1.3
-generate 1.4
-generate 1.5
-generate 1.6
+
+# Main logic to handle the argument using a switch case
+case "$#" in
+  1)
+    case "$1" in
+      '-h'|'--help')
+        echo "$DESC"
+        echo "$USAGE"
+        exit 0
+        ;;
+      *) # One argument provided: Call generate with the specific version
+        for version in "${CDX_VERSIONS[@]}"
+        do
+          if [[ "$1" == "$version" ]]
+          then
+            prepare
+            generate "$1"
+            exit 0
+          fi
+        done
+        echo "Error: unknown CDX_VERSION: $1"
+        echo "$USAGE"
+        exit 1
+        ;;
+    esac
+    ;;
+  0) # No arguments provided: Loop over all
+    for version in "${CDX_VERSIONS[@]}"
+    do
+      prepare
+      generate "$version"
+    done
+    exit 0
+    ;;
+  *) # More than one argument provided: Show usage help
+    echo "Usage: $USAGE"
+    exit 2
+    ;;
+esac
diff --git a/docgen/proto/gen.sh b/docgen/proto/gen.sh
@@ -1,48 +1,105 @@
 #!/bin/bash
 set -eu
 
+declare -a CDX_VERSIONS=(
+  '1.6'
+  '1.5'
+  '1.4'
+  '1.3'
+)
+
+# region help
+DESC="Generate HTML Schema navigator for CycloneDX ProtoBuf"
+USAGE="
+Usage: $0 [CDX_VERSION...]
+
+Supported values for CDX_VERSION: ${CDX_VERSIONS[*]}
+"
+# endregion help
+
+
 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"
+
+prepare() {
+  ## docs: https://github.com/pseudomuto/protoc-gen-doc
+  PROTOC_CONTAINER_IMAGE="pseudomuto/protoc-gen-doc:${PROTOC_GEN_DOC_VERSION}"
+  docker pull "$PROTOC_CONTAINER_IMAGE"
+}
 
 generate () {
-  version="$1"
-  title="CycloneDX v$version Protobuf Reference"
+  local version="$1"
+  local title="CycloneDX v$version Protobuf Reference"
   echo "Generating: $title"
 
-  OUT_DIR="$DOCS_PATH/$version/proto"
-  OUT_FILE="index.html"
+  local OUT_DIR="$DOCS_PATH/$version/proto"
+  local 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}" \
+    "$PROTOC_CONTAINER_IMAGE" \
       --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}" \
+    "$PROTOC_CONTAINER_IMAGE" \
     "$(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
+
+# Main logic to handle the argument using a switch case
+case "$#" in
+  1)
+    case "$1" in
+      '-h'|'--help')
+        echo "$DESC"
+        echo "$USAGE"
+        exit 0
+        ;;
+      *) # One argument provided: Call generate with the specific version
+        for version in "${CDX_VERSIONS[@]}"
+        do
+          if [[ "$1" == "$version" ]]
+          then
+            prepare
+            generate "$1"
+            exit 0
+          fi
+        done
+        echo "Error: unknown CDX_VERSION: $1"
+        echo "$USAGE"
+        exit 1
+        ;;
+    esac
+    ;;
+  0) # No arguments provided: Loop over all
+    for version in "${CDX_VERSIONS[@]}"
+    do
+      prepare
+      generate "$version"
+    done
+    exit 0
+    ;;
+  *) # More than one argument provided: Show usage help
+    echo "Usage: $USAGE"
+    exit 2
+    ;;
+esac
diff --git a/docgen/xml/gen.sh b/docgen/xml/gen.sh
@@ -1,33 +1,55 @@
 #!/bin/bash
 set -eu
 
+declare -a CDX_VERSIONS=(
+  '1.6'
+  '1.5'
+  '1.4'
+  '1.3'
+  '1.2'
+  '1.1'
+  '1.0'
+)
+
+# region help
+DESC="Generate HTML Schema navigator for CycloneDX XML"
+USAGE="
+Usage: $0 [CDX_VERSION...]
+
+Supported values for CDX_VERSION: ${CDX_VERSIONS[*]}
+"
+# endregion help
+
+
 THIS_PATH="$(realpath "$(dirname "$0")")"
 SCHEMA_PATH="$(realpath "$THIS_PATH/../../schema")"
 DOCS_PATH="$THIS_PATH/docs"
 
 SAXON_VERSION='10.9'
 
-# --
 
-
-rm -rf "$DOCS_PATH"
+# --
 
 
 SAXON_JAR="Saxon-HE-${SAXON_VERSION}.jar"
-if [ ! -f "$THIS_PATH/$SAXON_JAR" ]; then
-  echo "fetching $SAXON_JAR"
-  curl --output-dir "$THIS_PATH" -O \
-    "https://repo1.maven.org/maven2/net/sf/saxon/Saxon-HE/$SAXON_VERSION/$SAXON_JAR"
-fi
+prepare () {
+  if [ ! -f "$THIS_PATH/$SAXON_JAR" ]; then
+    echo "fetching $SAXON_JAR"
+    curl --output-dir "$THIS_PATH" -O \
+      "https://repo1.maven.org/maven2/net/sf/saxon/Saxon-HE/$SAXON_VERSION/$SAXON_JAR"
+  fi
+}
 
 
 generate () {
-  version="$1"
-  title="CycloneDX v$version XML Reference"
+  local version="$1"
+  local title="CycloneDX v$version XML Reference"
   echo "Generating: $title"
 
-  OUT_FILE="$DOCS_PATH/$version/xml/index.html"
-  mkdir -p "$(dirname "$OUT_FILE")"
+  local OUT_FILE="$DOCS_PATH/$version/xml/index.html"
+  local OUT_DIR="$(dirname "$OUT_FILE")"
+  rm -rf "$OUT_DIR"
+  mkdir -p "$OUT_DIR"
 
   ## docs: https://www.saxonica.com/documentation10/index.html#!using-xsl/commandline
   java -jar "$THIS_PATH/$SAXON_JAR" \
@@ -38,10 +60,42 @@ generate () {
     title="$title"
 }
 
-generate 1.0
-generate 1.1
-generate 1.2
-generate 1.3
-generate 1.4
-generate 1.5
-generate 1.6
+
+# Main logic to handle the argument using a switch case
+case "$#" in
+  1)
+    case "$1" in
+      '-h'|'--help')
+        echo "$DESC"
+        echo "$USAGE"
+        exit 0
+        ;;
+      *) # One argument provided: Call generate with the specific version
+        for version in "${CDX_VERSIONS[@]}"
+        do
+          if [[ "$1" == "$version" ]]
+          then
+            prepare
+            generate "$1"
+            exit 0
+          fi
+        done
+        echo "Error: unknown CDX_VERSION: $1"
+        echo "$USAGE"
+        exit 1
+        ;;
+    esac
+    ;;
+  0) # No arguments provided: Loop over all
+    for version in "${CDX_VERSIONS[@]}"
+    do
+      prepare
+      generate "$version"
+    done
+    exit 0
+    ;;
+  *) # More than one argument provided: Show usage help
+    echo "Usage: $USAGE"
+    exit 2
+    ;;
+esac
