Pull out docs and schema refactor from PR 692 (#730)

.github/workflows/zarf-schema-check.yml

@@ -1,9 +1,13 @@
+
 name: zarf-schema-check
 on:
   pull_request:
     paths:
       - "src/types/**"
       - "zarf.schema.json"
+      - "docs/4-user-guide/1-the-zarf-cli/3-zarf-schema.md"
+      - "src/cmd/**"
+      - "docs/4-user-guide/1-the-zarf-cli/100-cli-commands/**"
 
 # Abort prior jobs in the same workflow / PR
 concurrency:
@@ -31,18 +35,11 @@ jobs:
           key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
           restore-keys: |
             ${{ runner.os }}-go-
-
-      - name: "Backup Repo Schema Version"
-        run: "cp zarf.schema.json zarf.schema.json.bak"
-
-      - name: "Regenerate Schema"
-        run: "go run main.go internal config-schema > zarf.schema.json"
+      - name: "Regenerate Schema and Check that it Matches Generated"
+        run: "make test-docs-and-schema"
 
       - name: "Save test debug logs"
         uses: actions/upload-artifact@v3
         with:
           name: debug-log
           path: /tmp/zarf-*.log
-
-      - name: "Compare Schemas"
-        run: "cmp -s zarf.schema.json zarf.schema.json.bak"

.gitignore

@@ -4,6 +4,7 @@
 *.tar.gz
 *.tar
 *.tgz
+*.bak
 .vagrant
 zarf
 build

.hooks/backup-zarf-docs-and-schema.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env sh
+
+cp zarf.schema.json zarf.schema.json.bak
+cp docs/4-user-guide/3-zarf-schema.md docs/4-user-guide/3-zarf-schema.md.bak
+mkdir docs/4-user-guide/1-the-zarf-cli/100-cli-commands.bak/
+cp -r docs/4-user-guide/1-the-zarf-cli/100-cli-commands/* docs/4-user-guide/1-the-zarf-cli/100-cli-commands.bak/

.hooks/check-zarf-docs-and-schema.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env sh
+
+echo "Checking zarf.schema.json..."
+cmp -s zarf.schema.json zarf.schema.json.bak
+
+echo "Checking 3-zarf-schema.md..."
+cmp -s docs/4-user-guide/3-zarf-schema.md docs/4-user-guide/3-zarf-schema.md.bak
+
+echo "Checking CLI Docs..."
+DIFF=$(for f in `find docs/4-user-guide/1-the-zarf-cli/100-cli-commands/* ! -type l`;do diff -rq $f docs/4-user-guide/1-the-zarf-cli/100-cli-commands.bak/${f##*/};done)
+
+if [ -z "$DIFF" ]; then
+    echo "Success!"
+    exit 0
+else
+    echo $DIFF
+    exit 1
+fi

.hooks/create-zarf-schema.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+
+go run main.go internal config-schema > zarf.schema.json
+docker run -v $(pwd):/app -w /app --rm python:3.8-alpine /bin/sh -c "pip install json-schema-for-humans && generate-schema-doc --config-file .hooks/jsfh-config.json zarf.schema.json docs/4-user-guide/3-zarf-schema.md"

.hooks/zarf-jsfh-template/base.md

@@ -14,3 +14,5 @@
 {% if config.with_footer -%}
 Generated from [zarf.schema.json](https://github.com/defenseunicorns/zarf/blob/master/zarf.schema.json){% if config.footer_show_time %} on {{ get_local_time() }}{% endif %}
 {%- endif -%}
+
+{{ "\n" }}

Makefile

@@ -70,7 +70,16 @@ build-injector-registry-arm:
 
 docs-and-schema:
 	go run main.go internal generate-cli-docs
-	.hooks/verify-zarf-schema.sh
+	.hooks/create-zarf-schema.sh
+
+test-docs-and-schema:
+	.hooks/backup-zarf-docs-and-schema.sh
+	$(MAKE) docs-and-schema
+	.hooks/check-zarf-docs-and-schema.sh
+	$(MAKE) clean-docs-and-schema
+
+clean-docs-and-schema:
+	rm -r zarf.schema.json.bak docs/4-user-guide/3-zarf-schema.md.bak docs/4-user-guide/1-the-zarf-cli/100-cli-commands.bak/
 
 # Inject and deploy a new dev version of zarf agent for testing (should have an existing zarf agent deployemt)
 # @todo: find a clean way to support Kind or k3d: k3d image import $(tag)

docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_tools_sbom_convert.md

@@ -13,7 +13,20 @@ zarf tools sbom convert [SOURCE-SBOM] -o [FORMAT] [flags]
 ### Options
 
 ```
-  -h, --help   help for convert
+      --catalogers stringArray     enable one or more package catalogers
+  -d, --dockerfile string          include dockerfile for upload to Anchore Enterprise
+      --exclude stringArray        exclude paths from being scanned using a glob expression
+      --file string                file to write the default report output to (default is STDOUT)
+  -h, --help                       help for convert
+  -H, --host string                the hostname or URL of the Anchore Enterprise instance to upload to
+      --import-timeout uint        set a timeout duration (in seconds) for the upload to Anchore Enterprise (default 30)
+  -o, --output stringArray         report output format, options=[syft-json cyclonedx-xml cyclonedx-json github github-json spdx-tag-value spdx-json table text template] (default [table])
+      --overwrite-existing-image   overwrite an existing image during the upload to Anchore Enterprise
+  -p, --password string            the password to authenticate against Anchore Enterprise
+      --platform string            an optional platform specifier for container image sources (e.g. 'linux/arm64', 'linux/arm64/v8', 'arm64', 'linux')
+  -s, --scope string               selection of layers to catalog, options=[Squashed AllLayers] (default "Squashed")
+  -t, --template string            specify the path to a Go template file
+  -u, --username string            the username to authenticate against Anchore Enterprise
 ```
 
 ### Options inherited from parent commands

docs/4-user-guide/3-zarf-schema.md

@@ -1454,4 +1454,4 @@ Must be one of:
 </details>
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated from [zarf.schema.json](https://github.com/defenseunicorns/zarf/blob/master/zarf.schema.json)
+Generated from [zarf.schema.json](https://github.com/defenseunicorns/zarf/blob/master/zarf.schema.json)