feat: run doc tests from makefile

.github/workflows/docs.yml

@@ -46,20 +46,17 @@ jobs:
       - name: Check out code into the Go module directory
         uses: actions/checkout@v3
 
-      - name: Install dependencies
+      - name: Fail if auto-generated docs are modified
         run: |
-          sudo apt-get update
-          sudo apt-get install -y libgpgme-dev libbtrfs-dev libdevmapper-dev
-
-      - name: Ensure go modules are tidy
-        run: |
-          cd docs && make docs
-          if [[ -n $(git status -s) ]] ; then
+          set +e
+          cd docs && make test
+          exitcode=$?
+          echo "exitcode=$exitcode" >> $GITHUB_OUTPUT
+          if [ $exitcode -eq 1 ] ; then
             echo
             echo -e "\e[31mAuto-generated docs have been modified incorrectly."
             echo -e "\e[31mAuto-generated docs changes should be made in ./docs/src"
             echo -e "\e[31mPlease update your PR to address these issues.\e[0m"
-            git status -s
-            git diff --color
-            exit 1
+            exit $exitcode
           fi
+          exit $exitcode

docs/Makefile

@@ -4,6 +4,15 @@ DISTROS = "azure eks gke eks-fargate generic openshift"
 # Create custom resource docs to include in the documentation for a specific k8s distro.
 RESOURCE_DOCS = "openshift"
 
+# Documentation source directory.
+SOURCE_DIR ?= src/
+
+# Documentation build destination directory.
+BUILD_DESTINATION ?= ./
+
+# Documentation test build directory.
+TEST_DIR ?= testdir
+
 # Setting SHELL to bash allows bash commands to be executed by recipes.
 # Options are set to exit when a recipe line exits non-zero or a piped command fails.
 SHELL = /usr/bin/env bash -o pipefail
@@ -29,7 +38,14 @@ all: docs
 help: ## Display this help.
 	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z_0-9-]+:.*?##/ { printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)
 
+.PHONY: test
+test:
+	@mkdir -p $(TEST_DIR)
+	go run docgen.go -src=$(SOURCE_DIR) -out=$(TEST_DIR) -include-resource-docs=$(RESOURCE_DOCS) -distros=$(DISTROS)
+	git diff --color --no-index $(TEST_DIR)/resources $(BUILD_DESTINATION)/resources
+	git diff --color --no-index $(TEST_DIR)/deployment $(BUILD_DESTINATION)/deployment
+
 .PHONY: docs
 docs: ## Build the documentation using docgen.go.
 	@echo "Building documentation..."
-	go run docgen.go -src=src/ -out=./ -include-resource-docs=$(RESOURCE_DOCS) -distros=$(DISTROS)
+	go run docgen.go -src=$(SOURCE_DIR) -out=$(BUILD_DESTINATION) -include-resource-docs=$(RESOURCE_DOCS) -distros=$(DISTROS)

docs/deployment/openshift/resources/container/README.md

@@ -221,3 +221,4 @@ The following namespaces will be used by Falcon Operator.
 
 ### Additional Documentation
 End-to-end guide(s) to install Falcon-operator together with FalconContainer resource.
+ - [Deployment Guide for OpenShift](../../README.md)