Harden MkDocs generation and add PR validation checks

.github/workflows/validate.yml

@@ -2,7 +2,7 @@
 
 on:
   pull_request:
-    types:  opened
+    types: [opened, synchronize, reopened]
 
 jobs:
   oca_validation:
@@ -22,3 +22,32 @@
         run: |
           npm install -g ajv-cli
           ajv validate -s OCABundles/validators/schema.json -d 'OCABundles/**/OCABundle.json'
+
+  docs_validation:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: 3.x
+
+      - name: Install docs dependencies
+        run: pip install mkdocs-material
+
+      - name: Generate bundle indexes
+        run: ./scripts/gen_ocabundlesjson.sh
+
+      - name: Check generated indexes are up to date
+        run: git diff --exit-code -- ocabundles.json ocabundleslist.json
+
+      - name: Generate docs site assets
+        run: ./scripts/genMkdocsSite.sh
+
+      - name: Check mkdocs.yml generation is up to date
+        run: git diff --exit-code -- mkdocs.yml
+
+      - name: Validate docs build (strict)
+        run: mkdocs build --strict

.gitignore

@@ -22,3 +22,10 @@ yarn-error.log*
 /tmp
 .yarn
 /site
+
+# Generated by scripts/genMkdocsSite.sh
+/docs/OCABundles/
+/docs/governance/LICENSE.md
+/docs/governance/MAINTAINERS.md
+/docs/ocabundles.json
+/docs/ocabundleslist.json

OCABundles/schema/bcgov-digital-trust/IAS/README.md

@@ -0,0 +1 @@
+# Identity Assurance Services - Service BC

mkdocs.yml

@@ -1,6 +1,6 @@
 site_name: Aries OCA Bundles
 # Comment out the site_url for local testing, uncomment when pushing to the repo
-site_url: https://bcgov.github.io/aries-oca-bundles/
+# # # # site_url: https://bcgov.github.io/aries-oca-bundles/
 repo_name: bcgov/aries-oca-bundles
 repo_url: https://github.com/bcgov/aries-oca-bundles
 theme:
@@ -94,17 +94,17 @@ nav:
     - BC Gov:
       - OCABundles/schema/bcgov-digital-trust/business-card/README.md
       - OCABundles/schema/bcgov-digital-trust/business-card-nonprod/README.md
-      - OCABundles/schema/bcgov-digital-trust/IAS/digital-services-card-nonprod/README.md
+      - Identity Assurance Services - Service BC:
+        - OCABundles/schema/bcgov-digital-trust/IAS/digital-services-card-nonprod/README.md
       - LCRB:
         - OCABundles/schema/bcgov-digital-trust/LCRB/selling-it-right/README.md
         - OCABundles/schema/bcgov-digital-trust/LCRB/selling-it-right-showcase/README.md
         - OCABundles/schema/bcgov-digital-trust/LCRB/serving-it-right/README.md
         - OCABundles/schema/bcgov-digital-trust/LCRB/serving-it-right-showcase/README.md
         - OCABundles/schema/bcgov-digital-trust/LCRB/special-event-server/README.md
         - OCABundles/schema/bcgov-digital-trust/LCRB/special-event-server-showcase/README.md
-      - Law Society of BC:
-        - OCABundles/schema/bcgov-digital-trust/LSBC/Lawyer/Prod/README.md
-        - OCABundles/schema/bcgov-digital-trust/LSBC/Lawyer/Test/README.md
+      - OCABundles/schema/bcgov-digital-trust/LSBC/Lawyer/Prod/README.md
+      - OCABundles/schema/bcgov-digital-trust/LSBC/Lawyer/Test/README.md
       - Land Title and Survey Authority of BC:
         - OCABundles/schema/bcgov-digital-trust/LTSA/NewCredCredential/demo/README.md
         - OCABundles/schema/bcgov-digital-trust/LTSA/property-owner-v1/DevTest/README.md

scripts/gen_ocabundlesjson.sh

@@ -10,6 +10,7 @@ OCALISTJSON=${PWD}/ocabundleslist.json
 MKDOCSYML=${PWD}/mkdocs.yml
 TMPFILE=${PWD}/tmpfile.json
 ROOTDIR=${PWD}
+TMPMKDOCS=${PWD}/tmp-mkdocs.yml
 
 # Usage info
 show_help() {
@@ -84,7 +85,7 @@ insertBundleiframe () {
 
 addNav() {
     # Add entry to MKDocs Navigation
-    for ((num = 1; num <= ${INDENT}; num++)); do echo -n "  " >>$MKDOCSYML; done
+  for ((num = 1; num <= ${NAVINDENT}; num++)); do echo -n "  " >>$MKDOCSYML; done
     if [[ -f OCABundle.json ]]; then
       echo "- ${RELPATH}/README.md" >>$MKDOCSYML
       insertBundleiframe
@@ -95,14 +96,16 @@ addNav() {
 
 # Recursively process the folders
 processFolder() {
-    INDENT=$((INDENT+1))
+  local ADDED_NAV=0
     RELPATH=$(echo ${PWD} | sed -e "s#${ROOTDIR}/##")
     # If the right files are in the folder, process it
     if [[ -f README.md && -f OCABundle.json ]]; then
       processBundle README.md OCABundle.json
     fi
     if [[ -n "${GENMKDOCS}" && -f README.md ]]; then
       addNav # Relies on $ID existing from previous processing
+      NAVINDENT=$((NAVINDENT+1))
+      ADDED_NAV=1
     fi
     # Recurse into the directories of the folder
     for dir in *; do
@@ -116,22 +119,29 @@ processFolder() {
             cd ..
         fi
     done
-    INDENT=$((INDENT-1))
+    if [[ "${ADDED_NAV}" == "1" ]]; then
+      NAVINDENT=$((NAVINDENT-1))
+    fi
 }
 
 
 # Write the headers for the files
 echo -e "{" >${OCAIDSJSON}
 echo -e "[" >${OCALISTJSON}
 if [ "$1" == "mkdocs" ]; then
+    # Keep mkdocs nav generation idempotent by removing any existing
+    # generated OCA Bundles section before appending a fresh one.
+    if grep -q "^- OCA Bundles:" "${MKDOCSYML}"; then
+      awk 'BEGIN{drop=0} /^- OCA Bundles:/{drop=1} !drop{print}' "${MKDOCSYML}" > "${TMPMKDOCS}" && mv "${TMPMKDOCS}" "${MKDOCSYML}"
+    fi
     echo -e "- OCA Bundles:" >>${MKDOCSYML}
 fi
 
 # Start in the OCABundles folder
 cd OCABundles
 
 # Recursively process the folders
-INDENT=0
+NAVINDENT=1
 processFolder
 cd ..