diff --git a/README.md b/README.md index 789f795..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: ``` @@ -42,7 +51,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 +60,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/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 3d89656..18c89cd 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" @@ -39,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) } @@ -91,6 +94,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 } 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