From dbc3d5ef7312313bc10c8dac5032803d6589ace9 Mon Sep 17 00:00:00 2001 From: Sam Heilbron Date: Wed, 20 Nov 2024 08:35:42 -0700 Subject: [PATCH] docs: update markdown template (#571) Co-authored-by: Ariana W. --- changelog/v0.36.3/format-markdown-files.yaml | 6 +++ pkg/code-generator/docgen/generator.go | 38 ++++++++++++++----- .../templates/markdown/proto_file_template.go | 6 +-- pkg/code-generator/schemagen/crd.go | 4 +- .../crds/testing.solo.io_v1_MockResource.yaml | 2 +- ...testing.solo.io_v1_SimpleMockResource.yaml | 2 +- 6 files changed, 43 insertions(+), 15 deletions(-) create mode 100644 changelog/v0.36.3/format-markdown-files.yaml diff --git a/changelog/v0.36.3/format-markdown-files.yaml b/changelog/v0.36.3/format-markdown-files.yaml new file mode 100644 index 000000000..6da307e25 --- /dev/null +++ b/changelog/v0.36.3/format-markdown-files.yaml @@ -0,0 +1,6 @@ +changelog: +- type: FIX + issueLink: https://github.com/solo-io/solo-projects/issues/6612 + resolvesIssue: false + description: >- + Update the markdown templates to fit new formatting guidelines. \ No newline at end of file diff --git a/pkg/code-generator/docgen/generator.go b/pkg/code-generator/docgen/generator.go index 5150c78fa..c48db0857 100644 --- a/pkg/code-generator/docgen/generator.go +++ b/pkg/code-generator/docgen/generator.go @@ -147,11 +147,34 @@ func (d *DocsGen) FileHeader(filename string) string { return ".. Code generated by solo-kit. DO NOT EDIT." } if d.DocsOptions.Output == options.Hugo { - name := filepath.Base(filename) - if strings.HasSuffix(name, d.protoSuffix()) { - name = name[:len(name)-len(d.protoSuffix())] - } - return fmt.Sprintf(` + return d.hugoFileHeader(filename) + } + return ` +` +} + +func (d *DocsGen) hugoFileHeader(filename string) string { + name := filepath.Base(filename) + + // By default, the title of the page should match the file name + var title = name + + // Any files with an .sk.* suffix is one that is generated by solo-kit + // The title shouldn't include this suffix, so we remove it + if strings.HasSuffix(name, d.protoSuffix()) { + title = strings.TrimSuffix(name, d.protoSuffix()) + } + + // For proto files: + // - The title should not include the proto.sk.md suffix + // - The title should be CamelCase + // This means that custom_resource.proto.sk.md will have a title of CustomResource + protoSuffix := ".proto" + if strings.HasSuffix(title, protoSuffix) { + title = strcase.ToCamel(strings.TrimSuffix(title, protoSuffix)) + } + + return fmt.Sprintf(` --- title: "%s" weight: 5 @@ -159,10 +182,7 @@ weight: 5 -`, name) - } - return ` -` +`, title) } func (d *DocsGen) projectSuffix() string { diff --git a/pkg/code-generator/docgen/templates/markdown/proto_file_template.go b/pkg/code-generator/docgen/templates/markdown/proto_file_template.go index 763850cdd..99c8190e8 100644 --- a/pkg/code-generator/docgen/templates/markdown/proto_file_template.go +++ b/pkg/code-generator/docgen/templates/markdown/proto_file_template.go @@ -25,7 +25,7 @@ func ProtoFileTemplate(project *model.Project, docsOptions *options.DocsOptions) {{ end }} {{- if gt (len .Messages) 0 }} -#### Types: +**Types:** {{ $linkMessage := "- [{{ printfptr \"%v\" .Name }}](#{{ toAnchorLink \"%v\" .Name }}) {{- if (resourceForMessage .) }} **Top-Level Resource**{{ end }}" }} {{ $linkEnum := "- [{{ printfptr \"%v\" .Name }}](#{{ toAnchorLink \"%v\" .Name }})" }} @@ -35,7 +35,7 @@ func ProtoFileTemplate(project *model.Project, docsOptions *options.DocsOptions) {{- if gt (len .Enums) 0 }} -##### Enums: +**Enums:** {{ range .Enums}} - [{{ printfptr "%v" .Name }}](#{{ toAnchorLink "%v" .Name }}) @@ -44,7 +44,7 @@ func ProtoFileTemplate(project *model.Project, docsOptions *options.DocsOptions) {{ end}} -##### Source File: {{ githubLinkForFile "main" .Name }} +**Source File: {{ githubLinkForFile "main" .Name }}** {{ $msgLongInfo := ` + "`" + ` {{ $Message := . -}} diff --git a/pkg/code-generator/schemagen/crd.go b/pkg/code-generator/schemagen/crd.go index e87683f5b..88a5a65cb 100644 --- a/pkg/code-generator/schemagen/crd.go +++ b/pkg/code-generator/schemagen/crd.go @@ -22,6 +22,8 @@ const ( v1 = "apiextensions.k8s.io/v1" ) +const crdFileHeader = `CRD validation schema generated by solo-kit. DO NOT EDIT.` + var ( ApiVersionMismatch = func(expected, actual string) error { return eris.Errorf("Expected ApiVersion [%s] but found [%s]", expected, actual) @@ -37,7 +39,7 @@ func NewCrdWriter(crdDirectory string) *CrdWriter { fileWriter: &writer.DefaultFileWriter{ Root: crdDirectory, HeaderFromFilename: func(s string) string { - return fmt.Sprintf("# %s\n\n", writer.DefaultFileHeader) + return fmt.Sprintf("# %s\n\n", crdFileHeader) }, }, } diff --git a/test/mocks/crds/testing.solo.io_v1_MockResource.yaml b/test/mocks/crds/testing.solo.io_v1_MockResource.yaml index 9011cb6c7..645203258 100644 --- a/test/mocks/crds/testing.solo.io_v1_MockResource.yaml +++ b/test/mocks/crds/testing.solo.io_v1_MockResource.yaml @@ -1,4 +1,4 @@ -# Code generated by solo-kit. DO NOT EDIT. +# CRD validation schema generated by solo-kit. DO NOT EDIT. apiVersion: apiextensions.k8s.io/v1 kind: CustomResourceDefinition diff --git a/test/mocks/crds/testing.solo.io_v1_SimpleMockResource.yaml b/test/mocks/crds/testing.solo.io_v1_SimpleMockResource.yaml index 3e0831a05..e42f286f5 100644 --- a/test/mocks/crds/testing.solo.io_v1_SimpleMockResource.yaml +++ b/test/mocks/crds/testing.solo.io_v1_SimpleMockResource.yaml @@ -1,4 +1,4 @@ -# Code generated by solo-kit. DO NOT EDIT. +# CRD validation schema generated by solo-kit. DO NOT EDIT. apiVersion: apiextensions.k8s.io/v1 kind: CustomResourceDefinition