Add helm docs generation script (hashicorp#727)

lawliet89 · Dec 17, 2020 · 6e022bf · 6e022bf
1 parent a2717e3
commit 6e022bf
Show file tree

Hide file tree

Showing 11 changed files with 4,371 additions and 10 deletions.
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -31,15 +31,15 @@ jobs:
           name: Run Unit Tests
           command: bats ./test/unit
 
-  go-fmt-and-vet:
+  go-fmt-and-vet-acceptance:
     executor: go
     steps:
       - checkout
 
       # Restore go module cache if there is one
       - restore_cache:
           keys:
-            - consul-helm-modcache-v1-{{ checksum "test/acceptance/go.mod" }}
+            - consul-helm-acceptance-modcache-v1-{{ checksum "test/acceptance/go.mod" }}
 
       - run:
           name: go mod download
@@ -48,7 +48,7 @@ jobs:
 
       # Save go module cache if the go.mod file has changed
       - save_cache:
-          key: consul-helm-modcache-v1-{{ checksum "test/acceptance/go.mod" }}
+          key: consul-helm-acceptance-modcache-v1-{{ checksum "test/acceptance/go.mod" }}
           paths:
             - "/go/pkg/mod"
 
@@ -76,7 +76,7 @@ jobs:
       # Restore go module cache if there is one
       - restore_cache:
           keys:
-            - consul-helm-modcache-v1-{{ checksum "test/acceptance/go.mod" }}
+            - consul-helm-acceptance-modcache-v1-{{ checksum "test/acceptance/go.mod" }}
 
       - run: mkdir -p $TEST_RESULTS
 
@@ -199,7 +199,7 @@ jobs:
       # Restore go module cache if there is one
       - restore_cache:
           keys:
-            - consul-helm-modcache-v1-{{ checksum "test/acceptance/go.mod" }}
+            - consul-helm-acceptance-modcache-v1-{{ checksum "test/acceptance/go.mod" }}
 
       - run: mkdir -p $TEST_RESULTS
 
@@ -273,7 +273,7 @@ jobs:
       # Restore go module cache if there is one
       - restore_cache:
           keys:
-            - consul-helm-modcache-v1-{{ checksum "test/acceptance/go.mod" }}
+            - consul-helm-acceptance-modcache-v1-{{ checksum "test/acceptance/go.mod" }}
 
       - run: mkdir -p $TEST_RESULTS
 
@@ -355,7 +355,7 @@ jobs:
       # Restore go module cache if there is one
       - restore_cache:
           keys:
-            - consul-helm-modcache-v1-{{ checksum "test/acceptance/go.mod" }}
+            - consul-helm-acceptance-modcache-v1-{{ checksum "test/acceptance/go.mod" }}
 
       - run: mkdir -p $TEST_RESULTS
 
@@ -440,7 +440,7 @@ jobs:
       # Restore go module cache if there is one
       - restore_cache:
           keys:
-            - consul-helm-modcache-v1-{{ checksum "test/acceptance/go.mod" }}
+            - consul-helm-acceptance-modcache-v1-{{ checksum "test/acceptance/go.mod" }}
 
       - run: mkdir -p $TEST_RESULTS
 
@@ -466,6 +466,84 @@ jobs:
           fail_only: true
           failure_message: "OpenShift acceptance tests failed. Check the logs at: ${CIRCLE_BUILD_URL}"
 
+  go-fmt-and-vet-helm-gen:
+    executor: go
+    steps:
+      - checkout
+
+      # Restore go module cache if there is one
+      - restore_cache:
+          keys:
+            - consul-helm-helm-gen-modcache-v1-{{ checksum "hack/helm-reference-gen/go.mod" }}
+
+      - run:
+          name: go mod download
+          working_directory: hack/helm-reference-gen
+          command: go mod download
+
+      # Save go module cache if the go.mod file has changed
+      - save_cache:
+          key: consul-helm-helm-gen-modcache-v1-{{ checksum "hack/helm-reference-gen/go.mod" }}
+          paths:
+            - "/go/pkg/mod"
+
+      # check go fmt output because it does not report non-zero when there are fmt changes
+      - run:
+          name: check go fmt
+          command: |
+            files=$(go fmt ./...)
+            if [ -n "$files" ]; then
+              echo "The following file(s) do not conform to go fmt:"
+              echo "$files"
+              exit 1
+            fi
+
+      - run:
+          name: go vet
+          working_directory: hack/helm-reference-gen
+          command: go vet ./...
+
+  unit-helm-gen:
+    executor: go
+    steps:
+      - checkout
+
+      # Restore go module cache if there is one
+      - restore_cache:
+          keys:
+            - consul-helm-helm-gen-modcache-v1-{{ checksum "hack/helm-reference-gen/go.mod" }}
+
+      - run: mkdir -p $TEST_RESULTS
+
+      - run:
+          name: Run tests
+          working_directory: hack/helm-reference-gen
+          command: |
+            gotestsum --junitfile $TEST_RESULTS/gotestsum-report.xml ./... -- -p 4
+
+      - store_test_results:
+          path: /tmp/test-results
+      - store_artifacts:
+          path: /tmp/test-results
+
+  test-helm-gen:
+    executor: go
+    steps:
+      - checkout
+
+      # Restore go module cache if there is one
+      - restore_cache:
+          keys:
+            - consul-helm-helm-gen-modcache-v1-{{ checksum "hack/helm-reference-gen/go.mod" }}
+
+      - run: mkdir -p $TEST_RESULTS
+
+      - run:
+          name: Run tests
+          working_directory: hack/helm-reference-gen
+          command: |
+            go run ./... -validate
+
   update-helm-charts-index:
     docker:
       - image: docker.mirror.hashicorp.services/circleci/golang:latest
@@ -498,10 +576,15 @@ workflows:
   version: 2
   test:
     jobs:
-      - go-fmt-and-vet
+      - go-fmt-and-vet-acceptance
+      - go-fmt-and-vet-helm-gen
       - unit-acceptance-framework:
           requires:
-            - go-fmt-and-vet
+            - go-fmt-and-vet-acceptance
+      - unit-helm-gen:
+          requires:
+            - go-fmt-and-vet-helm-gen
+      - test-helm-gen
       - unit-helm2
       - unit-helm3
       - acceptance:

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -378,4 +378,68 @@ Here are some things to consider before adding a test:
   either Consul itself or consul-k8s? In that case, it should be tested there rather than in the Helm chart.
   For example, we don't expect acceptance tests to include all the permutations of the consul-k8s commands
   and their respective flags. Something like that should be tested in the consul-k8s repository.
+
+## Helm Reference Docs
+
+The helm reference docs (https://www.consul.io/docs/k8s/helm) are automatically
+generated from our `values.yaml` file.
+
+### Code Generation
+
+To generate the docs and update the `helm.mdx` file, run:
+
+```bash
+make gen-docs consul=<path-to-consul-repo>
+```
+
+Where `<path-to-consul-repo>` is the relative or absolute path to the `hashicorp/consul`
+repo on disk.
+
+### values.yaml Annotations
+
+The code generation will attempt to parse the `values.yaml` file and extract all
+the information needed to create the documentation but depending on the yaml
+you may need to add some annotations.
+
+#### @type
+If the type is unknown because the field is `null` or you wish to override
+the type, use `@type`:
+
+```yaml
+# My docs
+# @type: string
+myKey: null
+```
 
+#### @default
+The default will be set to the current value but you may want to override
+it for specific use cases:
+
+```yaml
+server:
+  # My docs
+  # @default: global.enabled
+  enabled: "-"
+```
+
+#### @recurse
+In rare cases, we don't want the documentation generation to recurse deeper
+into the object. To stop the recursion, set `@recurse: false`.
+For example, the ingress gateway ports config looks like:
+
+```yaml
+# Port docs
+# @type: array<map>
+# @default: [{port: 8080, port: 8443}]
+# @recurse: false
+ports:
+- port: 8080
+  nodePort: null
+- port: 8443
+  nodePort: null
+```
+
+So that the documentation can look like:
+```markdown
+- `ports` ((#v-ingressgateways-defaults-service-ports)) (`array<map>: [{port: 8080, port: 8443}]`) - Port docs
+```
diff --git a/Makefile b/Makefile
@@ -3,4 +3,9 @@ TEST_IMAGE?=consul-helm-test
 test-docker:
 	@docker build --rm -t '$(TEST_IMAGE)' -f $(CURDIR)/test/docker/Test.dockerfile $(CURDIR)
 
+# Generate Helm reference docs from values.yaml and update Consul website.
+# Usage: make gen-docs consul=<path-to-consul-repo>
+gen-docs:
+	@cd hack/helm-reference-gen; go run ./... $(consul)
+
 .PHONY: test-docker