docs: update markdown format (#10362)

Author: sam-heilbron

Makefile

@@ -447,30 +447,14 @@ generate-changelog: ## Generate a changelog entry
 #----------------------------------------------------------------------------------
 # Generate CRD Reference Documentation
 #
-# We are trying to migrate our APIs and CRDs to be built using Kubebuilder.
-#
-# Historically, our docs are generated using Protocol Buffers as the source of truth,
-# and code generation (https://github.com/solo-io/solo-kit/tree/main/pkg/code-generator/docgen)
-# to generate the Markdown for these APIs.
-#
-# With the migration to Kubebuilder, protos are no longer the source of truth, and we must rely on other means to
-# generate documentation. As https://github.com/kubernetes-sigs/controller-tools/issues/240 calls out, there isn't an agreed
-# upon approach yet. We chose to use https://github.com/fybrik/crdoc as it allows us to generate the Markdown for our docs,
-# which is used by Hugo. Other tools produced HTML, which wouldn't have worked for our current setup.
-#
+# See docs/content/crds/README.md for more details.
 #----------------------------------------------------------------------------------
 
-GWPARAMS_INPUT_CRD := install/helm/gloo/crds/gateway.gloo.solo.io_gatewayparameters.yaml
-GWPARAMS_OUTPUT_MARKDOWN := docs/content/reference/api/github.com/solo-io/gloo/projects/gateway2/api/v1alpha1/gateway_parameters.md
-
-DRA_INPUT_CRD := install/helm/gloo/crds/gateway.gloo.solo.io_directresponses.yaml
-DRA_OUTPUT_MARKDOWN := docs/content/reference/api/github.com/solo-io/gloo/projects/gateway2/api/v1alpha1/direct_response_action.md
-
-
+# To run this command correctly, you must have executed `install-go-tools`
 .PHONY: generate-crd-reference-docs
 generate-crd-reference-docs:
-	$(DEPSGOBIN)/crdoc --resources $(GWPARAMS_INPUT_CRD) --output $(GWPARAMS_OUTPUT_MARKDOWN)
-	$(DEPSGOBIN)/crdoc --resources $(DRA_INPUT_CRD) --output $(DRA_OUTPUT_MARKDOWN)
+	go run docs/content/crds/generate.go
+
 
 #----------------------------------------------------------------------------------
 # Generate mocks

changelog/v1.18.0-rc2/update-gloo-docs-format.yaml

@@ -0,0 +1,10 @@
+changelog:
+  - type: NON_USER_FACING
+    issueLink: https://github.com/solo-io/solo-projects/issues/6612
+    resolvesIssue: false
+    description: >-
+      Generate the documentation using the updated markdown templates to fit new formatting guidelines.
+  - type: DEPENDENCY_BUMP
+    dependencyOwner: solo-io
+    dependencyRepo: solo-kit
+    dependencyTag: v0.36.3

docs/content/crds/README.md

@@ -0,0 +1,39 @@
+# CRD Reference Documentation
+
+### Background
+We are trying to migrate our APIs and CRDs to be built using Kubebuilder.
+
+Historically, our docs are generated using Protocol Buffers as the source of truth, and code generation (https://github.com/solo-io/solo-kit/tree/main/pkg/code-generator/docgen) to generate the Markdown for these APIs.
+
+With the migration to Kubebuilder, protos are no longer the source of truth, and we must rely on other means to
+generate documentation. As https://github.com/kubernetes-sigs/controller-tools/issues/240 calls out, there isn't an agreed
+upon approach yet. We chose to use https://github.com/fybrik/crdoc as it allows us to generate the Markdown for our docs,
+which is used by Hugo. Other tools produced HTML, which wouldn't have worked for our current setup.
+
+### Which CRDs are documented using this mechanism?
+We opted to only add this to our newer APIs, which do not rely on protos as the source of truth. This means the following CRDs are affected:
+- GatewayParameters
+- DirectReponseAction
+
+### How are the reference docs for our proto-based APIs generated?
+We rely on our [solo-kit docgen](https://github.com/solo-io/solo-kit/tree/main/pkg/code-generator/docgen) code.
+
+### How do I regenerate the documentation locally?
+1. Install crdoc locally
+```bash
+make install-go-gools
+```
+
+2. Run the generation script.
+
+This can be done by either using the go script directly:
+```bash
+ go run docs/content/crds/generate.go
+```
+or relying on the Make target:
+```bash
+ make generate-crd-reference-docs
+```
+
+### When is this regenerated in CI?
+When running `make generated-code`.

docs/content/crds/generate.go

@@ -0,0 +1,107 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/hashicorp/go-multierror"
+	"github.com/rotisserie/eris"
+	"github.com/solo-io/gloo/pkg/utils/cmdutils"
+	"github.com/solo-io/gloo/projects/gateway2/api/v1alpha1"
+	"github.com/solo-io/skv2/codegen/util"
+	"github.com/stoewer/go-strcase"
+	"k8s.io/apimachinery/pkg/runtime/schema"
+)
+
+var (
+	// crdocBinary is assumed to be installed locally to this path
+	// see the `install-go-tools` target in the Makefile
+	crdocBinary = filepath.Join(util.GetModuleRoot(), "_output", ".bin", "crdoc")
+)
+
+func main() {
+	err := generateCrdReferenceDocs(context.Background())
+	if err != nil {
+		fmt.Println(err)
+		os.Exit(1)
+	}
+}
+
+// generateCrdReferenceDocs is the entrypoint to our automation for updating CRD reference markdown files
+func generateCrdReferenceDocs(ctx context.Context) error {
+	gvks := []schema.GroupVersionKind{
+		v1alpha1.GatewayParametersGVK,
+		v1alpha1.DirectResponseGVK,
+	}
+
+	outErr := &multierror.Error{}
+	for _, gvk := range gvks {
+		err := generateCrdReferenceMarkdown(ctx, gvk)
+		outErr = multierror.Append(outErr, err)
+	}
+
+	return outErr.ErrorOrNil()
+}
+
+func generateCrdReferenceMarkdown(ctx context.Context, gvk schema.GroupVersionKind) error {
+	// sourceFile is the path to the CRD. This is used as the source of truth for the CRD reference docs
+	sourceFile := filepath.Join(
+		"install",
+		"helm",
+		"gloo",
+		"crds",
+		fmt.Sprintf("%s_%s.yaml", gvk.Group, strings.ToLower(kindPlural(gvk))),
+	)
+
+	// outputFile is the path to the generated reference markdown file.
+	// NOTE: For now, this is tightly coupled to the `gateway2` project, since that is where the APIs that we
+	// rely on are defined, though that may need to change in the future
+	outputFile := filepath.Join(
+		"docs",
+		"content",
+		"reference",
+		"api",
+		"github.com",
+		"solo-io",
+		"gloo",
+		"projects",
+		"gateway2",
+		"api",
+		gvk.Version,
+		fmt.Sprintf("%s.md", strcase.SnakeCase(kindPlural(gvk))))
+
+	// templateFile is the path to the file used as the template for our docs
+	templateFile := filepath.Join(
+		"docs",
+		"content",
+		"crds",
+		"templates",
+		"markdown.tmpl")
+
+	cmd := cmdutils.Command(ctx, crdocBinary,
+		"--resources",
+		sourceFile,
+		"--output",
+		outputFile,
+		"--template",
+		templateFile,
+	)
+	runErr := cmd.Run()
+
+	if runErr.Cause() != nil {
+		return eris.Wrapf(runErr.Cause(), "%s produced error %s", runErr.PrettyCommand(), runErr.Error())
+	}
+	return nil
+}
+
+// kindPlural returns the pluralized kind for a given GVK.
+// This is hacky, but is useful because CRD files are named using this format, so we need a way to look up that file name
+// If the name of the file is incorrect, a developer will realize this because the script will fail with a file not found error.
+func kindPlural(gvk schema.GroupVersionKind) string {
+	// ensure that kind which ends in s, is not duplicated
+	// ie GatewayParameters becomes GatewayParameters, not GatewayParameterss
+	return strings.TrimSuffix(gvk.Kind, "s") + "s"
+}

docs/content/crds/templates/markdown.tmpl

@@ -0,0 +1,102 @@
+# API Reference
+
+Packages:
+{{range .Groups}}
+- [{{.Group}}/{{.Version}}](#{{ anchorize (printf "%s/%s" .Group .Version) }})
+{{- end -}}{{/* range .Groups */}}
+
+{{- range .Groups }}
+{{- $group := . }}
+
+# {{.Group}}/{{.Version}}
+
+Resource Types:
+{{range .Kinds}}
+- [{{.Name}}](#{{ anchorize .Name }})
+{{end}}{{/* range .Kinds */}}
+
+{{range .Kinds}}
+{{$kind := .}}
+## {{.Name}}
+<sup><sup>[↩ Parent](#{{ anchorize (printf "%s/%s" $group.Group $group.Version) }} )</sup></sup>
+
+{{range .Types}}
+
+{{if not .IsTopLevel}}
+### {{.Name}}
+{{if .ParentKey}}<sup><sup>[↩ Parent](#{{.ParentKey}})</sup></sup>{{end}}
+{{end}}
+
+
+{{.Description}}
+
+<table>
+    <thead>
+        <tr>
+            <th>Name</th>
+            <th>Type</th>
+            <th>Description</th>
+            <th>Required</th>
+        </tr>
+    </thead>
+    <tbody>
+      {{- if .IsTopLevel -}}
+      <tr>
+      <td><b>apiVersion</b></td>
+      <td>string</td>
+      <td>{{$group.Group}}/{{$group.Version}}</td>
+      <td>true</td>
+      </tr>
+      <tr>
+      <td><b>kind</b></td>
+      <td>string</td>
+      <td>{{$kind.Name}}</td>
+      <td>true</td>
+      </tr>
+      <tr>
+      <td><b><a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#objectmeta-v1-meta">metadata</a></b></td>
+      <td>object</td>
+      <td>Refer to the Kubernetes API documentation for the fields of the `metadata` field.</td>
+      <td>true</td>
+      </tr>
+      {{- end -}}
+      {{- range .Fields -}}
+      <tr>
+        <td><b>{{if .TypeKey}}<a href="#{{.TypeKey}}">{{.Name}}</a>{{else}}{{.Name}}{{end}}</b></td>
+        <td>{{.Type}}</td>
+        <td>
+          {{.Description}}<br/>
+          {{- if or .Schema.XValidations .Schema.Format .Schema.Enum .Schema.Default .Schema.Minimum .Schema.Maximum }}
+          <br/>
+          {{- end}}
+          {{- if .Schema.XValidations }}
+            <i>Validations</i>:
+            {{- range .Schema.XValidations -}}
+              <li>{{ .Rule }}: {{ .Message }}</li>
+            {{- end -}}
+          {{- end }}
+          {{- if .Schema.Format }}
+            <i>Format</i>: {{ .Schema.Format }}<br/>
+          {{- end }}
+          {{- if .Schema.Enum }}
+            <i>Enum</i>: {{ .Schema.Enum | toStrings | join ", " }}<br/>
+          {{- end }}
+          {{- if .Schema.Default }}
+            <i>Default</i>: {{ .Schema.Default }}<br/>
+          {{- end }}
+          {{- if .Schema.Minimum }}
+            <i>Minimum</i>: {{ .Schema.Minimum }}<br/>
+          {{- end }}
+          {{- if .Schema.Maximum }}
+            <i>Maximum</i>: {{ .Schema.Maximum }}<br/>
+          {{- end }}
+        </td>
+        <td>{{.Required}}</td>
+      </tr>
+      {{- end -}}
+    </tbody>
+</table>
+
+{{- end}}{{/* range .Types */}}
+{{- end}}{{/* range .Kinds */}}
+{{- end}}{{/* range .Groups */}}