Skip to content

Commit e2ca028

Browse files
sam-heilbronsam-heilbron
authored
docs: update markdown format (#10362)
1 parent e290622 commit e2ca028

File tree

153 files changed

+672
-429
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

153 files changed

+672
-429
lines changed

‎Makefile

+4-20
Original file line numberDiff line numberDiff line change
@@ -447,30 +447,14 @@ generate-changelog: ## Generate a changelog entry
447447
#----------------------------------------------------------------------------------
448448
# Generate CRD Reference Documentation
449449
#
450-
# We are trying to migrate our APIs and CRDs to be built using Kubebuilder.
451-
#
452-
# Historically, our docs are generated using Protocol Buffers as the source of truth,
453-
# and code generation (https://github.com/solo-io/solo-kit/tree/main/pkg/code-generator/docgen)
454-
# to generate the Markdown for these APIs.
455-
#
456-
# With the migration to Kubebuilder, protos are no longer the source of truth, and we must rely on other means to
457-
# generate documentation. As https://github.com/kubernetes-sigs/controller-tools/issues/240 calls out, there isn't an agreed
458-
# upon approach yet. We chose to use https://github.com/fybrik/crdoc as it allows us to generate the Markdown for our docs,
459-
# which is used by Hugo. Other tools produced HTML, which wouldn't have worked for our current setup.
460-
#
450+
# See docs/content/crds/README.md for more details.
461451
#----------------------------------------------------------------------------------
462452

463-
GWPARAMS_INPUT_CRD := install/helm/gloo/crds/gateway.gloo.solo.io_gatewayparameters.yaml
464-
GWPARAMS_OUTPUT_MARKDOWN := docs/content/reference/api/github.com/solo-io/gloo/projects/gateway2/api/v1alpha1/gateway_parameters.md
465-
466-
DRA_INPUT_CRD := install/helm/gloo/crds/gateway.gloo.solo.io_directresponses.yaml
467-
DRA_OUTPUT_MARKDOWN := docs/content/reference/api/github.com/solo-io/gloo/projects/gateway2/api/v1alpha1/direct_response_action.md
468-
469-
453+
# To run this command correctly, you must have executed `install-go-tools`
470454
.PHONY: generate-crd-reference-docs
471455
generate-crd-reference-docs:
472-
$(DEPSGOBIN)/crdoc --resources $(GWPARAMS_INPUT_CRD) --output $(GWPARAMS_OUTPUT_MARKDOWN)
473-
$(DEPSGOBIN)/crdoc --resources $(DRA_INPUT_CRD) --output $(DRA_OUTPUT_MARKDOWN)
456+
go run docs/content/crds/generate.go
457+
474458

475459
#----------------------------------------------------------------------------------
476460
# Generate mocks

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

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
changelog:
2+
- type: NON_USER_FACING
3+
issueLink: https://github.com/solo-io/solo-projects/issues/6612
4+
resolvesIssue: false
5+
description: >-
6+
Generate the documentation using the updated markdown templates to fit new formatting guidelines.
7+
- type: DEPENDENCY_BUMP
8+
dependencyOwner: solo-io
9+
dependencyRepo: solo-kit
10+
dependencyTag: v0.36.3

‎docs/content/crds/README.md

+39
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# CRD Reference Documentation
2+
3+
### Background
4+
We are trying to migrate our APIs and CRDs to be built using Kubebuilder.
5+
6+
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.
7+
8+
With the migration to Kubebuilder, protos are no longer the source of truth, and we must rely on other means to
9+
generate documentation. As https://github.com/kubernetes-sigs/controller-tools/issues/240 calls out, there isn't an agreed
10+
upon approach yet. We chose to use https://github.com/fybrik/crdoc as it allows us to generate the Markdown for our docs,
11+
which is used by Hugo. Other tools produced HTML, which wouldn't have worked for our current setup.
12+
13+
### Which CRDs are documented using this mechanism?
14+
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:
15+
- GatewayParameters
16+
- DirectReponseAction
17+
18+
### How are the reference docs for our proto-based APIs generated?
19+
We rely on our [solo-kit docgen](https://github.com/solo-io/solo-kit/tree/main/pkg/code-generator/docgen) code.
20+
21+
### How do I regenerate the documentation locally?
22+
1. Install crdoc locally
23+
```bash
24+
make install-go-gools
25+
```
26+
27+
2. Run the generation script.
28+
29+
This can be done by either using the go script directly:
30+
```bash
31+
go run docs/content/crds/generate.go
32+
```
33+
or relying on the Make target:
34+
```bash
35+
make generate-crd-reference-docs
36+
```
37+
38+
### When is this regenerated in CI?
39+
When running `make generated-code`.

‎docs/content/crds/generate.go

+107
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
package main
2+
3+
import (
4+
"context"
5+
"fmt"
6+
"os"
7+
"path/filepath"
8+
"strings"
9+
10+
"github.com/hashicorp/go-multierror"
11+
"github.com/rotisserie/eris"
12+
"github.com/solo-io/gloo/pkg/utils/cmdutils"
13+
"github.com/solo-io/gloo/projects/gateway2/api/v1alpha1"
14+
"github.com/solo-io/skv2/codegen/util"
15+
"github.com/stoewer/go-strcase"
16+
"k8s.io/apimachinery/pkg/runtime/schema"
17+
)
18+
19+
var (
20+
// crdocBinary is assumed to be installed locally to this path
21+
// see the `install-go-tools` target in the Makefile
22+
crdocBinary = filepath.Join(util.GetModuleRoot(), "_output", ".bin", "crdoc")
23+
)
24+
25+
func main() {
26+
err := generateCrdReferenceDocs(context.Background())
27+
if err != nil {
28+
fmt.Println(err)
29+
os.Exit(1)
30+
}
31+
}
32+
33+
// generateCrdReferenceDocs is the entrypoint to our automation for updating CRD reference markdown files
34+
func generateCrdReferenceDocs(ctx context.Context) error {
35+
gvks := []schema.GroupVersionKind{
36+
v1alpha1.GatewayParametersGVK,
37+
v1alpha1.DirectResponseGVK,
38+
}
39+
40+
outErr := &multierror.Error{}
41+
for _, gvk := range gvks {
42+
err := generateCrdReferenceMarkdown(ctx, gvk)
43+
outErr = multierror.Append(outErr, err)
44+
}
45+
46+
return outErr.ErrorOrNil()
47+
}
48+
49+
func generateCrdReferenceMarkdown(ctx context.Context, gvk schema.GroupVersionKind) error {
50+
// sourceFile is the path to the CRD. This is used as the source of truth for the CRD reference docs
51+
sourceFile := filepath.Join(
52+
"install",
53+
"helm",
54+
"gloo",
55+
"crds",
56+
fmt.Sprintf("%s_%s.yaml", gvk.Group, strings.ToLower(kindPlural(gvk))),
57+
)
58+
59+
// outputFile is the path to the generated reference markdown file.
60+
// NOTE: For now, this is tightly coupled to the `gateway2` project, since that is where the APIs that we
61+
// rely on are defined, though that may need to change in the future
62+
outputFile := filepath.Join(
63+
"docs",
64+
"content",
65+
"reference",
66+
"api",
67+
"github.com",
68+
"solo-io",
69+
"gloo",
70+
"projects",
71+
"gateway2",
72+
"api",
73+
gvk.Version,
74+
fmt.Sprintf("%s.md", strcase.SnakeCase(kindPlural(gvk))))
75+
76+
// templateFile is the path to the file used as the template for our docs
77+
templateFile := filepath.Join(
78+
"docs",
79+
"content",
80+
"crds",
81+
"templates",
82+
"markdown.tmpl")
83+
84+
cmd := cmdutils.Command(ctx, crdocBinary,
85+
"--resources",
86+
sourceFile,
87+
"--output",
88+
outputFile,
89+
"--template",
90+
templateFile,
91+
)
92+
runErr := cmd.Run()
93+
94+
if runErr.Cause() != nil {
95+
return eris.Wrapf(runErr.Cause(), "%s produced error %s", runErr.PrettyCommand(), runErr.Error())
96+
}
97+
return nil
98+
}
99+
100+
// kindPlural returns the pluralized kind for a given GVK.
101+
// 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
102+
// If the name of the file is incorrect, a developer will realize this because the script will fail with a file not found error.
103+
func kindPlural(gvk schema.GroupVersionKind) string {
104+
// ensure that kind which ends in s, is not duplicated
105+
// ie GatewayParameters becomes GatewayParameters, not GatewayParameterss
106+
return strings.TrimSuffix(gvk.Kind, "s") + "s"
107+
}

‎docs/content/crds/templates/markdown.tmpl

+102
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# API Reference
2+
3+
Packages:
4+
{{range .Groups}}
5+
- [{{.Group}}/{{.Version}}](#{{ anchorize (printf "%s/%s" .Group .Version) }})
6+
{{- end -}}{{/* range .Groups */}}
7+
8+
{{- range .Groups }}
9+
{{- $group := . }}
10+
11+
# {{.Group}}/{{.Version}}
12+
13+
Resource Types:
14+
{{range .Kinds}}
15+
- [{{.Name}}](#{{ anchorize .Name }})
16+
{{end}}{{/* range .Kinds */}}
17+
18+
{{range .Kinds}}
19+
{{$kind := .}}
20+
## {{.Name}}
21+
<sup><sup>[↩ Parent](#{{ anchorize (printf "%s/%s" $group.Group $group.Version) }} )</sup></sup>
22+
23+
{{range .Types}}
24+
25+
{{if not .IsTopLevel}}
26+
### {{.Name}}
27+
{{if .ParentKey}}<sup><sup>[↩ Parent](#{{.ParentKey}})</sup></sup>{{end}}
28+
{{end}}
29+
30+
31+
{{.Description}}
32+
33+
<table>
34+
<thead>
35+
<tr>
36+
<th>Name</th>
37+
<th>Type</th>
38+
<th>Description</th>
39+
<th>Required</th>
40+
</tr>
41+
</thead>
42+
<tbody>
43+
{{- if .IsTopLevel -}}
44+
<tr>
45+
<td><b>apiVersion</b></td>
46+
<td>string</td>
47+
<td>{{$group.Group}}/{{$group.Version}}</td>
48+
<td>true</td>
49+
</tr>
50+
<tr>
51+
<td><b>kind</b></td>
52+
<td>string</td>
53+
<td>{{$kind.Name}}</td>
54+
<td>true</td>
55+
</tr>
56+
<tr>
57+
<td><b><a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#objectmeta-v1-meta">metadata</a></b></td>
58+
<td>object</td>
59+
<td>Refer to the Kubernetes API documentation for the fields of the `metadata` field.</td>
60+
<td>true</td>
61+
</tr>
62+
{{- end -}}
63+
{{- range .Fields -}}
64+
<tr>
65+
<td><b>{{if .TypeKey}}<a href="#{{.TypeKey}}">{{.Name}}</a>{{else}}{{.Name}}{{end}}</b></td>
66+
<td>{{.Type}}</td>
67+
<td>
68+
{{.Description}}<br/>
69+
{{- if or .Schema.XValidations .Schema.Format .Schema.Enum .Schema.Default .Schema.Minimum .Schema.Maximum }}
70+
<br/>
71+
{{- end}}
72+
{{- if .Schema.XValidations }}
73+
<i>Validations</i>:
74+
{{- range .Schema.XValidations -}}
75+
<li>{{ .Rule }}: {{ .Message }}</li>
76+
{{- end -}}
77+
{{- end }}
78+
{{- if .Schema.Format }}
79+
<i>Format</i>: {{ .Schema.Format }}<br/>
80+
{{- end }}
81+
{{- if .Schema.Enum }}
82+
<i>Enum</i>: {{ .Schema.Enum | toStrings | join ", " }}<br/>
83+
{{- end }}
84+
{{- if .Schema.Default }}
85+
<i>Default</i>: {{ .Schema.Default }}<br/>
86+
{{- end }}
87+
{{- if .Schema.Minimum }}
88+
<i>Minimum</i>: {{ .Schema.Minimum }}<br/>
89+
{{- end }}
90+
{{- if .Schema.Maximum }}
91+
<i>Maximum</i>: {{ .Schema.Maximum }}<br/>
92+
{{- end }}
93+
</td>
94+
<td>{{.Required}}</td>
95+
</tr>
96+
{{- end -}}
97+
</tbody>
98+
</table>
99+
100+
{{- end}}{{/* range .Types */}}
101+
{{- end}}{{/* range .Kinds */}}
102+
{{- end}}{{/* range .Groups */}}

‎docs/content/reference/api/envoy/annotations/deprecation.proto.sk.md

+2-2
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/content/reference/api/envoy/api/v2/route/route.proto.sk.md

+3-3
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/content/reference/api/extproto/ext.proto.sk.md

+2-2
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/content/reference/api/github.com/solo-io/gloo/projects/gateway/api/v1/external_options.proto.sk.md

+3-3
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)