Merge pull request #888 from humio/mike/genapidocs

Generate markdown API docs for CRD's

.github/workflows/ci.yaml

@@ -2,14 +2,15 @@ on: push
 name: CI
 jobs:
   checks:
-    name: Run Tests
+    name: Run Checks
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
     - uses: actions/setup-go@v5
       with:
         go-version: '1.22.2'
-    - shell: bash
+    - name: Generate manifests
+      shell: bash
       run: |
         make manifests
         if [[ -n $(git status -s) ]] ; then
@@ -20,6 +21,26 @@ jobs:
           git diff
           exit 1
         fi
+    - name: Generate API docs
+      shell: bash
+      run: |
+        make apidocs
+        if [[ -n $(git status -s) ]] ; then
+          echo "Generating API docs leaves tracked files in a modified state."
+          echo "Ensure to include updated API docs in this PR."
+          echo "This is usually done by running 'make apidocs' and running 'git add ...' for the files that was modified by generating manifests."
+          git status -s
+          git diff
+          exit 1
+        fi
+  test:
+    name: Run Tests
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-go@v5
+      with:
+        go-version: '1.22.2'
     - shell: bash
       run: |
         make test

Makefile

@@ -162,3 +162,23 @@ ifeq (,$(shell PATH=$$PATH:$(GOBIN) which ginkgo))
 endif
 GINKGO=$(GOBIN)/ginkgo
 endif
+
+.PHONY: crdoc
+crdoc:
+ifneq (,$(shell which crdoc))
+CRDOC=$(shell which crdoc)
+else
+ifeq (,$(shell PATH=$$PATH:$(GOBIN) which crdoc))
+	@{ \
+	set -ex ;\
+	which go ;\
+	go version ;\
+	go install fybrik.io/crdoc@6247ceaefc6bdb5d1a038278477feeda509e4e0c ;\
+	crdoc --version ;\
+	}
+endif
+CRDOC=$(GOBIN)/crdoc
+endif
+
+apidocs: manifests crdoc
+	$(CRDOC) --resources config/crd/bases --output docs/api.md