From 8b3fd1cd089f89fdcb76175e509ac16ab1d36de0 Mon Sep 17 00:00:00 2001 From: Alisdair MacLeod Date: Thu, 4 Sep 2025 15:12:46 +0100 Subject: [PATCH 1/2] Create a new output mode for creating group and version combination --- README.md | 10 +++++++++- config/config.go | 5 +++-- renderer/renderer.go | 19 +++++++++++++++++++ 3 files changed, 31 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 789f795..08c8500 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ crd-ref-docs \ ``` Default output mode writes all data to a single output file. -You can choose between single mode and group mode by specifying the output mode. +You can choose between single mode, group mode, or version mode by specifying the output mode. In group mode, separate files are created for each API group, ensuring that the specified output path is an existing directory. ``` crd-ref-docs \ @@ -51,6 +51,14 @@ crd-ref-docs \ --output-path=./docs \ --output-mode=group ``` +In version mode, separate files are created for each API group and version combination, ensuring that the specified output path is an existing directory. +``` +crd-ref-docs \ + --source-path=$GOPATH/src/github.com/elastic/cloud-on-k8s/pkg/apis \ + --config=config.yaml \ + --output-path=./docs \ + --output-mode=version +``` ### Configuration diff --git a/config/config.go b/config/config.go index b1c792e..b5f3cad 100644 --- a/config/config.go +++ b/config/config.go @@ -63,8 +63,9 @@ type KnownType struct { } const ( - OutputModeSingle = "single" - OutputModeGroup = "group" + OutputModeSingle = "single" + OutputModeGroup = "group" + OutputModeGroupVersion = "version" ) type Flags struct { diff --git a/renderer/renderer.go b/renderer/renderer.go index 3d89656..1e96fd5 100644 --- a/renderer/renderer.go +++ b/renderer/renderer.go @@ -21,6 +21,7 @@ import ( "io/fs" "os" "path/filepath" + "strings" "text/template" "github.com/elastic/crd-ref-docs/config" @@ -91,6 +92,24 @@ func renderTemplate(tmpl *template.Template, conf *config.Config, fileExtension return err } + if err := tmpl.ExecuteTemplate(file, mainTemplate, []types.GroupVersionDetails{gvd}); err != nil { + return err + } + } + case config.OutputModeGroupVersion: + for _, gvd := range gvds { + // To avoid filenames containing filepath separators, replace them with a non-separator value. + // Using the GroupVersionString is the core difference between this output mode and the regular + // group mode. + name := strings.NewReplacer("/", "-").Replace(gvd.GroupVersionString()) + + fileName := fmt.Sprintf("%s.%s", name, fileExtension) + file, err := createOutFile(conf.OutputPath, true, fileName) + defer file.Close() + if err != nil { + return err + } + if err := tmpl.ExecuteTemplate(file, mainTemplate, []types.GroupVersionDetails{gvd}); err != nil { return err } From b2bfbbcf6c73858bd8728d259d3d0096db47bf4a Mon Sep 17 00:00:00 2001 From: Alisdair MacLeod Date: Thu, 4 Sep 2025 15:35:13 +0100 Subject: [PATCH 2/2] Add an mdx renderer --- README.md | 9 ++ renderer/markdown-x.go | 119 ++++++++++++++++++++++++++ renderer/renderer.go | 2 + templates/markdown-x/gv_details.tpl | 19 ++++ templates/markdown-x/gv_list.tpl | 19 ++++ templates/markdown-x/type.tpl | 49 +++++++++++ templates/markdown-x/type_members.tpl | 8 ++ templates/templates.go | 1 + 8 files changed, 226 insertions(+) create mode 100644 renderer/markdown-x.go create mode 100644 templates/markdown-x/gv_details.tpl create mode 100644 templates/markdown-x/gv_list.tpl create mode 100644 templates/markdown-x/type.tpl create mode 100644 templates/markdown-x/type_members.tpl diff --git a/README.md b/README.md index 08c8500..fe85ba0 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,15 @@ crd-ref-docs \ --renderer=markdown ``` +Additionally, a very basic MDX renderer is provided: + +``` +crd-ref-docs \ + --source-path=$GOPATH/src/github.com/elastic/cloud-on-k8s/pkg/apis \ + --config=config.yaml \ + --renderer=mdx +``` + Default templates are embedded in the binary. You may provide your own templates by specifying the templates directory: ``` diff --git a/renderer/markdown-x.go b/renderer/markdown-x.go new file mode 100644 index 0000000..cf50c70 --- /dev/null +++ b/renderer/markdown-x.go @@ -0,0 +1,119 @@ +// Licensed to Elasticsearch B.V. under one or more contributor +// license agreements. See the NOTICE file distributed with +// this work for additional information regarding copyright +// ownership. Elasticsearch B.V. licenses this file to you under +// the Apache License, Version 2.0 (the "License"); you may +// not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. +package renderer + +import ( + "fmt" + "io/fs" + "os" + "strings" + "text/template" + + "github.com/Masterminds/sprig" + "github.com/elastic/crd-ref-docs/config" + "github.com/elastic/crd-ref-docs/templates" + "github.com/elastic/crd-ref-docs/types" +) + +type MarkdownXRenderer struct { + *MarkdownRenderer +} + +func NewMarkdownXRenderer(conf *config.Config) (*MarkdownXRenderer, error) { + markdownRenderer, err := NewMarkdownRenderer(conf) + if err != nil { + return nil, err + } + return &MarkdownXRenderer{markdownRenderer}, nil +} + +func (m *MarkdownXRenderer) ToFuncMap() template.FuncMap { + fm := m.MarkdownRenderer.ToFuncMap() + fm["RenderLocalLink"] = m.RenderLocalLink + fm["RenderGVLink"] = m.RenderGVLink + fm["RenderTypeLink"] = m.RenderTypeLink + fm["RenderFieldDoc"] = m.RenderFieldDoc + return fm +} + +func (m *MarkdownXRenderer) Render(gvd []types.GroupVersionDetails) error { + funcMap := combinedFuncMap(funcMap{prefix: "markdown", funcs: m.ToFuncMap()}, funcMap{funcs: sprig.TxtFuncMap()}) + + var tpls fs.FS + if m.conf.TemplatesDir != "" { + tpls = os.DirFS(m.conf.TemplatesDir) + } else { + sub, err := fs.Sub(templates.Root, "markdown-x") + if err != nil { + return err + } + tpls = sub + } + + tmpl, err := loadTemplate(tpls, funcMap) + if err != nil { + return err + } + + return renderTemplate(tmpl, m.conf, "mdx", gvd) +} + +func (m *MarkdownXRenderer) RenderTypeLink(t *types.Type) string { + text := m.SimplifiedTypeName(t) + + link, local := m.LinkForType(t) + if link == "" { + return text + } + + if local { + return m.RenderLocalLink(text) + } else { + return m.RenderExternalLink(link, text) + } +} + +func (m *MarkdownXRenderer) RenderLocalLink(text string) string { + anchor := strings.ToLower( + strings.NewReplacer( + " ", "-", + ".", "", + "/", "", + "(", "", + ")", "", + ).Replace(text), + ) + + label := strings.NewReplacer("{", "\\{").Replace(text) + + return fmt.Sprintf("[%s](#%s)", label, anchor) +} + +func (m *MarkdownXRenderer) RenderGVLink(gv types.GroupVersionDetails) string { + return m.RenderLocalLink(gv.GroupVersionString()) +} + +func (m *MarkdownXRenderer) RenderFieldDoc(text string) string { + out := text + + // escape inlined markup + out = strings.ReplaceAll(out, "<", "<") + out = strings.ReplaceAll(out, ">", ">") + + // Pass to the inner renderer for further processing + return m.MarkdownRenderer.RenderFieldDoc(out) +} diff --git a/renderer/renderer.go b/renderer/renderer.go index 1e96fd5..18c89cd 100644 --- a/renderer/renderer.go +++ b/renderer/renderer.go @@ -40,6 +40,8 @@ func New(conf *config.Config) (Renderer, error) { return NewAsciidoctorRenderer(conf) case "markdown": return NewMarkdownRenderer(conf) + case "mdx": + return NewMarkdownXRenderer(conf) default: return nil, fmt.Errorf("unknown renderer: %s", conf.Renderer) } diff --git a/templates/markdown-x/gv_details.tpl b/templates/markdown-x/gv_details.tpl new file mode 100644 index 0000000..30ad0d7 --- /dev/null +++ b/templates/markdown-x/gv_details.tpl @@ -0,0 +1,19 @@ +{{- define "gvDetails" -}} +{{- $gv := . -}} + +## {{ $gv.GroupVersionString }} + +{{ $gv.Doc }} + +{{- if $gv.Kinds }} +### Resource Types +{{- range $gv.SortedKinds }} +- {{ $gv.TypeForKind . | markdownRenderTypeLink }} +{{- end }} +{{ end }} + +{{ range $gv.SortedTypes }} +{{ template "type" . }} +{{ end }} + +{{- end -}} diff --git a/templates/markdown-x/gv_list.tpl b/templates/markdown-x/gv_list.tpl new file mode 100644 index 0000000..3123cf0 --- /dev/null +++ b/templates/markdown-x/gv_list.tpl @@ -0,0 +1,19 @@ +{{- define "gvList" -}} +{{- $groupVersions := . -}} + + + + + +# API Reference + +## Packages +{{- range $groupVersions }} +- {{ markdownRenderGVLink . }} +{{- end }} + +{{ range $groupVersions }} +{{ template "gvDetails" . }} +{{ end }} + +{{- end -}} diff --git a/templates/markdown-x/type.tpl b/templates/markdown-x/type.tpl new file mode 100644 index 0000000..3e1edb5 --- /dev/null +++ b/templates/markdown-x/type.tpl @@ -0,0 +1,49 @@ +{{- define "type" -}} +{{- $type := . -}} +{{- if markdownShouldRenderType $type -}} + +### {{ $type.Name }} + +{{ if $type.IsAlias }}_Underlying type:_ _{{ markdownRenderTypeLink $type.UnderlyingType }}_{{ end }} + +{{ $type.Doc }} + +{{ if $type.Validation -}} +_Validation:_ +{{- range $type.Validation }} +- {{ . }} +{{- end }} +{{- end }} + +{{ if $type.References -}} +_Appears in:_ +{{- range $type.SortedReferences }} +- {{ markdownRenderTypeLink . }} +{{- end }} +{{- end }} + +{{ if $type.Members -}} +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +{{ if $type.GVK -}} +| `apiVersion` _string_ | `{{ $type.GVK.Group }}/{{ $type.GVK.Version }}` | | | +| `kind` _string_ | `{{ $type.GVK.Kind }}` | | | +{{ end -}} + +{{ range $type.Members -}} +| `{{ .Name }}` _{{ markdownRenderType .Type }}_ | {{ template "type_members" . }} | {{ markdownRenderDefault .Default }} | {{ range .Validation -}} {{ markdownRenderFieldDoc . }}
{{ end }} | +{{ end -}} + +{{ end -}} + +{{ if $type.EnumValues -}} +| Field | Description | +| --- | --- | +{{ range $type.EnumValues -}} +| `{{ .Name }}` | {{ markdownRenderFieldDoc .Doc }} | +{{ end -}} +{{ end -}} + + +{{- end -}} +{{- end -}} diff --git a/templates/markdown-x/type_members.tpl b/templates/markdown-x/type_members.tpl new file mode 100644 index 0000000..041758a --- /dev/null +++ b/templates/markdown-x/type_members.tpl @@ -0,0 +1,8 @@ +{{- define "type_members" -}} +{{- $field := . -}} +{{- if eq $field.Name "metadata" -}} +Refer to Kubernetes API documentation for fields of `metadata`. +{{- else -}} +{{ markdownRenderFieldDoc $field.Doc }} +{{- end -}} +{{- end -}} diff --git a/templates/templates.go b/templates/templates.go index a7234d2..3b09bda 100644 --- a/templates/templates.go +++ b/templates/templates.go @@ -4,4 +4,5 @@ import "embed" //go:embed asciidoctor //go:embed markdown +//go:embed markdown-x var Root embed.FS