Publish documentation to UDR instead of the Consul repo (#4953)

* Rename docs path to something more meaningful

* Write docs to UDR instead of consul repo

* Update instructions for UDR instead of consul repo

* Fix incorrect error reporting code

Co-authored-by: Ruben Nic <RubenSandwich@users.noreply.github.com>

* Fail Early

Fail early if any of the following are true:
- versionMetadata is empty
- versionMetadata fails to parse
- latestVersion is not set

---------

Co-authored-by: Ruben Nic <RubenSandwich@users.noreply.github.com>
Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>

Author: 3 people

CONTRIBUTING.md

@@ -1184,23 +1184,35 @@ generated from our `values.yaml` file.
 
 To generate the docs and update the `helm.mdx` file:
 
-1. Fork `hashicorp/consul` (https://github.com/hashicorp/consul) on GitHub.
+1. Fork `hashicorp/web-unified-docs` (https://github.com/hashicorp/web-unified-docs) on GitHub.
 1. Clone your fork:
    ```shell-session
-   git clone https://github.com/<your-username>/consul.git
+   git clone https://github.com/<your-username>/web-unified-docs.git
+   ```
+1. Change directory to `web-unified-docs`:
+   ```shell-session
+   cd /path/to/web-unified-docs
+   ```
+1. Install NPM dependencies
+   ```shell-session
+   npm i
+   ```
+1. Compile version metadata file
+   ```shell-session
+   npm run prebuild -- --onlyVersionMetadata
    ```
 1. Change directory into your `consul-k8s` repo:
    ```shell-session
    cd /path/to/consul-k8s
    ```
 1. Run `make gen-helm-docs` using the path to your consul (not consul-k8s) repo:
    ```shell-session
-   make gen-helm-docs consul=<path-to-consul-repo>
+   make gen-helm-docs docsRepo=<path-to-docs-repo>
    # Examples:
-   # make gen-helm-docs consul=/Users/my-name/code/hashicorp/consul
-   # make gen-helm-docs consul=../consul
+   # make gen-helm-docs docsRepo=/Users/my-name/code/web-unified-docs
+   # make gen-helm-docs docsRepo=../web-unified-docs
    ```
-1. Open up a pull request to `hashicorp/consul` (in addition to your `hashicorp/consul-k8s` pull request)
+1. Open up a pull request to `hashicorp/web-unified-docs` (in addition to your `hashicorp/consul-k8s` pull request)
 
 ### values.yaml Annotations
 

Makefile

@@ -15,7 +15,7 @@ GOTESTSUM_PATH?=$(shell command -v gotestsum)
 
 .PHONY: gen-helm-docs
 gen-helm-docs: ## Generate Helm reference docs from values.yaml and update Consul website. Usage: make gen-helm-docs consul=<path-to-consul-repo>.
-	@cd hack/helm-reference-gen; go run ./... $(consul)
+	@cd hack/helm-reference-gen; go run ./... $(docsRepo)
 
 .PHONY: copy-crds-to-chart
 copy-crds-to-chart: ## Copy generated CRD YAML into charts/consul. Usage: make copy-crds-to-chart
@@ -315,7 +315,7 @@ ifeq (, $(shell which copywrite))
 	@echo "Installing copywrite"
 	@go install github.com/hashicorp/copywrite@latest
 endif
-	@copywrite headers --spdx "MPL-2.0" 
+	@copywrite headers --spdx "MPL-2.0"
 
 ##@ CI Targets
 

hack/helm-reference-gen/main.go

@@ -22,6 +22,7 @@ import (
 	"text/template"
 
 	"gopkg.in/yaml.v3"
+	"encoding/json"
 )
 
 const (
@@ -75,7 +76,7 @@ var (
 
 func main() {
 	validateFlag := flag.Bool("validate", false, "only validate that the markdown can be generated, don't actually generate anything")
-	consulRepoPath := "../../../consul"
+	docsRepoPath := "../../../web-unified-docs"
 	flag.Parse()
 
 	if len(os.Args) > 3 {
@@ -86,17 +87,17 @@ func main() {
 	if !*validateFlag {
 		// Only argument is path to Consul repo. If not set then we default.
 		if len(os.Args) < 2 {
-			abs, _ := filepath.Abs(consulRepoPath)
-			fmt.Printf("Defaulting to Consul repo path: %s\n", abs)
+			abs, _ := filepath.Abs(docsRepoPath)
+			fmt.Printf("Defaulting to docs repo path: %s\n", abs)
 		} else {
 			// Support absolute and relative paths to the Consul repo.
 			if filepath.IsAbs(os.Args[1]) {
-				consulRepoPath = os.Args[1]
+				docsRepoPath = os.Args[1]
 			} else {
-				consulRepoPath = filepath.Join("../..", os.Args[1])
+				docsRepoPath = filepath.Join("../..", os.Args[1])
 			}
-			abs, _ := filepath.Abs(consulRepoPath)
-			fmt.Printf("Using Consul repo path: %s\n", abs)
+			abs, _ := filepath.Abs(docsRepoPath)
+			fmt.Printf("Using docs repo path: %s\n", abs)
 		}
 	}
 
@@ -118,8 +119,54 @@ func main() {
 		os.Exit(0)
 	}
 
-	// Otherwise we'll go on to write the changes to the helm docs.
-	helmReferenceFile := filepath.Join(consulRepoPath, "website/content/docs/reference/k8s/helm.mdx")
+	// Open the JSON file containing our list of Consul versions. If this doesn't
+	// exist, you'll need to generate it by running `npm run build --onlyVersionMetadata`
+	// in the web-unified-docs repo.
+	versionMetadataPath := filepath.Join(docsRepoPath, "app/api/versionMetadata.json")
+	versionMetadataBytes, err := os.ReadFile(versionMetadataPath)
+	if err != nil {
+		fmt.Println(err.Error())
+		os.Exit(1)
+	}
+
+	// Parse versionMetadata.json so we can choose a Consul docs version if desired
+	// Expected shape: { "consul": [{"version":"v1.22.x","releaseStage":"stable","isLatest":true}, ...], ... }
+	type ProductVersion struct {
+		Version      string `json:"version"`
+		ReleaseStage string `json:"releaseStage"`
+		IsLatest     bool   `json:"isLatest"`
+	}
+
+	// Fail early: require non-empty file, successful parse, and an explicit latest version.
+	if len(versionMetadataBytes) == 0 {
+		fmt.Printf("%s is empty: ", versionMetadataPath)
+		os.Exit(1)
+	}
+
+	var versionMap map[string][]ProductVersion
+	if err := json.Unmarshal(versionMetadataBytes, &versionMap); err != nil {
+		fmt.Printf("failed to parse %s: %v\n", versionMetadataPath, err.Error())
+		os.Exit(1)
+	}
+
+	consulList, ok := versionMap["consul"]
+	if !ok || len(consulList) == 0 {
+		fmt.Printf("no 'consul' key or versions in %s: \n", versionMetadataPath)
+		os.Exit(1)
+	}
+
+	var latestVersion string
+	for _, pv := range consulList {
+		if pv.IsLatest {
+			latestVersion = pv.Version
+			break
+		}
+	}
+	if latestVersion == "" {
+		fmt.Printf("no Consul version marked isLatest=true in %s; cannot continue: \n", versionMetadataPath)
+		os.Exit(1)
+	}
+	helmReferenceFile := filepath.Join(docsRepoPath, "content/consul", latestVersion, "content/docs/reference/k8s/helm.mdx")
 	helmReferenceBytes, err := os.ReadFile(helmReferenceFile)
 	if err != nil {
 		fmt.Println(err.Error())