Skip to content

Improve apiref with experimental and ignored CRD description #4132

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
+126 −275
Open

Improve apiref with experimental and ignored CRD description #4132

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
47d554f
Improve apiref with experimental and ignored CRD description
rikatz Sep 28, 2025
ddff277
Add warning icon on experimental API
rikatz Sep 29, 2025
8134f0b
Improve table readability
rikatz Oct 1, 2025
2990a97
Add experimental warning on the type field
rikatz Oct 1, 2025
66c0ffe
Fix makefile, ignore specx.md properly
rikatz Oct 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,3 +57,5 @@ go.work.sum
.venv/
release/
site-src/reference/spec.md
site-src/reference/specx.md

13 changes: 2 additions & 11 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -175,7 +175,7 @@ build-docs:
docker run --name $(DOCS_BUILD_CONTAINER_NAME) --rm -v ${PWD}:/docs gaie/mkdocs build

.PHONY: build-docs-netlify
build-docs-netlify:
build-docs-netlify: api-ref-docs
hack/mkdocs/generate.sh
pip install -r hack/mkdocs/image/requirements.txt
python -m mkdocs build
Expand All @@ -195,13 +195,4 @@ update-mkdocs-nav:

.PHONY: api-ref-docs
api-ref-docs:
crd-ref-docs \
--source-path=${PWD}/apis \
--config=crd-ref-docs.yaml \
--renderer=markdown \
--output-path=${PWD}/site-src/reference/spec.md
crd-ref-docs \
--source-path=${PWD}/apisx \
--config=crd-ref-docs.yaml \
--renderer=markdown \
--output-path=${PWD}/site-src/reference/specx.md
hack/mkdocs/generate.sh
5 changes: 5 additions & 0 deletions hack/crd-ref-templates/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
The templates contained in this directory were copied from https://github.com/elastic/crd-ref-docs/tree/master/templates/markdown
and had the following modifications:

- `type.tpl` - Adds an "experimental" marker in case the API field is marked as "experimental"
- `type_members.tpl` - Removes the text between tags `<gateway:util:excludeFromCRD></gateway:util:excludeFromCRD>`
19 changes: 19 additions & 0 deletions hack/crd-ref-templates/gv_details.tpl
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 -}}
17 changes: 17 additions & 0 deletions hack/crd-ref-templates/gv_list.tpl
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
{{- define "gvList" -}}
{{- $groupVersions := . -}}
---
hide:
- toc
---
# API Reference

{{- range $groupVersions }}
- {{ markdownRenderGVLink . }}
{{- end }}

{{ range $groupVersions }}
{{ template "gvDetails" . }}
{{ end }}

{{- end -}}
54 changes: 54 additions & 0 deletions hack/crd-ref-templates/type.tpl
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
{{- 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 . }}
{{- range .Fields -}}
{{- if eq .Type.Name $type.Name -}}
{{- if contains "<gateway:experimental>" .Doc }} :warning: Experimental in `{{.Name}}` field {{- end }}
{{- end }}
{{- end }}
{{ 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 }}_ {{- if contains "<gateway:experimental>" .Doc -}}<br /> :warning: **Experimental**{{ end -}}| {{ template "type_members" . }} | {{ markdownRenderDefault .Default }} | {{ range .Validation -}} {{ markdownRenderFieldDoc . }} <br />{{ end }} |
{{ end -}}
Comment on lines +38 to +40
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tbh I think that Default and Validation could well live in the first cell of the row, under the Experimental warning, and then we can have only two columns, which should make the descriptions a lot more readable.

Maybe something like:

Suggested change
{{ range $type.Members -}}
| `{{ .Name }}` _{{ markdownRenderType .Type }}_ {{- if contains "<gateway:experimental>" .Doc -}}<br /> :warning: **Experimental**{{ end -}}| {{ template "type_members" . }} | {{ markdownRenderDefault .Default }} | {{ range .Validation -}} {{ markdownRenderFieldDoc . }} <br />{{ end }} |
{{ end -}}
{{ range $type.Members -}}
| `{{ .Name }}` _{{ markdownRenderType .Type }}_ {{- if contains "<gateway:experimental>" .Doc -}}<br /> :warning: **Experimental**{{ end -}}< br /> {{ markdownRenderDefault .Default }} {{ range .Validation -}} <br />{{ markdownRenderFieldDoc . }}{{ end }} | {{ template "type_members" . }} | | |
{{ end -}}

Ideally, we can find a way to make the table take up more of the page as well, maybe by removing the in-page TOC?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

last famous words: seem simple. I have tried changing the defaults and validations to first field, but the misalignment caused by some validations that are huge are worst than the current situation.

The markdown tables are not really very configurable (https://squidfunk.github.io/mkdocs-material/reference/data-tables/#column-alignment) unless we do some CSS change, so I think changing the defaults and validations here will be harder.

Removing the TOC OTOH was doable and things got a bit more clear (I will push it soon)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

another approach I have tried was to move defaults and validations to a tooltip/annotation like, where when you hover over an information icon it would show each of them, but still the gain is not great on the Markdown tables.

We have fields that have a type of "LocalObjectReferenceWithNamespacesAndLasers" and rendering this still makes the first column be bigger than the second


{{ end -}}

{{ if $type.EnumValues -}}
| Field | Description |
| --- | --- |
{{ range $type.EnumValues -}}
| `{{ .Name }}` | {{ markdownRenderFieldDoc .Doc }} |
{{ end -}}
{{ end -}}


{{- end -}}
{{- end -}}
9 changes: 9 additions & 0 deletions hack/crd-ref-templates/type_members.tpl
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
{{- define "type_members" -}}
{{- $field := . -}}
{{- if eq $field.Name "metadata" -}}
Refer to Kubernetes API documentation for fields of `metadata`.
{{- else -}}
{{- $cleanDoc := regexReplaceAllLiteral "(?s)<gateway:util:excludeFromCRD>.*?</gateway:util:excludeFromCRD>" $field.Doc "" -}}
{{ markdownRenderFieldDoc $cleanDoc }}
{{- end -}}
{{- end -}}
8 changes: 8 additions & 0 deletions hack/mkdocs/generate.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,5 +32,13 @@ go install github.com/elastic/crd-ref-docs
${GOBIN}/crd-ref-docs \
--source-path=${PWD}/apis \
--config=crd-ref-docs.yaml \
--templates-dir=${PWD}/hack/crd-ref-templates/ \
--renderer=markdown \
--output-path=${PWD}/site-src/reference/spec.md

${GOBIN}/crd-ref-docs \
--source-path=${PWD}/apisx \
--config=crd-ref-docs.yaml \
--templates-dir=${PWD}/hack/crd-ref-templates/ \
--renderer=markdown \
--output-path=${PWD}/site-src/reference/specx.md
263 changes: 0 additions & 263 deletions site-src/reference/specx.md
View file
Open in desktop

This file was deleted.

11 changes: 10 additions & 1 deletion site-src/stylesheets/extra.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,8 @@
}

/* Increase size of logo */
.md-header__button.md-logo img, .md-header__button.md-logo svg {
.md-header__button.md-logo img,
.md-header__button.md-logo svg {
height: 1.8rem;
}

Expand All @@ -18,6 +19,7 @@
.md-header__button.md-logo {
display: block;
}

.md-tabs {
display: block;
}
Expand All @@ -31,6 +33,7 @@
[data-md-toggle=search]:checked~.md-header .md-search__form {
border-radius: .5rem .5rem 0 0;
}

[dir=ltr] .md-search__output {
border-radius: 0 0 .5rem .5rem;
}
Expand All @@ -41,3 +44,9 @@ img.center {
margin: 20px auto;
width: 550px;
}

/* Make tables use the maximum available size */
.md-typeset__table {
min-width: 100%;
width: 100%;
}