Skip to content

Commit 5f819fd

Browse files
pebrcpebrc
authored
Migrate API reference to markdown (#8501)
Part of #8498 https://docs-v3-preview.elastic.dev/elastic/cloud-on-k8s/pull/8501/reference/ Adjust the templating for the API reference. Markdown was modelled after #8496 Differences to the manually migrated files: API reference tool creates a single file not a file per group, we could however adjust that if needed.
1 parent 4423110 commit 5f819fd

File tree

10 files changed

+2610
-2582
lines changed

10 files changed

+2610
-2582
lines changed

‎docs/docset.yml‎

Lines changed: 489 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/reference/api-docs.asciidoc‎

Lines changed: 0 additions & 2546 deletions
This file was deleted.

‎docs/reference/api-docs.md‎

Lines changed: 2073 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/reference/index.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
mapped_pages:
3+
- https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-reference.html
4+
applies_to:
5+
deployment:
6+
eck: all
7+
---
8+
9+
# Elastic Cloud on Kubernetes [k8s-reference]
10+
11+
This section contains reference information for {{eck}}, including:
12+
13+
* [API Reference](./api-docs.md)

‎docs/reference/toc.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
toc:
2+
- file: index.md
3+
- file: api-docs.md

‎hack/api-docs/build.sh‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,9 +37,9 @@ build_docs() {
3737
echo "Generating API reference documentation"
3838
"${BIN_DIR}"/crd-ref-docs --source-path="${REPO_ROOT}"/pkg/apis \
3939
--config="${SCRIPT_DIR}"/config.yaml \
40-
--renderer=asciidoctor \
40+
--renderer=markdown \
4141
--templates-dir="${SCRIPT_DIR}"/templates \
42-
--output-path="${DOCS_DIR}"/reference/api-docs.asciidoc
42+
--output-path="${DOCS_DIR}"/reference/api-docs.md
4343
)
4444
}
4545

‎hack/api-docs/templates/gv_details.tpl‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,15 @@
11
{{- define "gvDetails" -}}
22
{{- $gv := . -}}
3-
[id="{{ asciidocGroupVersionID $gv | asciidocRenderAnchorID }}"]
4-
== {{ $gv.GroupVersionString }}
3+
4+
% TODO add function to crd-ref-docs return anchor used in links docs-v3 does not seem to produce valid markdown anchors
5+
## {{ $gv.GroupVersionString }} [#{{ markdownGroupVersionID $gv | replace "-" "" }}]
56

67
{{ $gv.Doc }}
78

89
{{- if $gv.Kinds }}
9-
.Resource Types
10+
### Resource Types
1011
{{- range $gv.SortedKinds }}
11-
- {{ $gv.TypeForKind . | asciidocRenderTypeLink }}
12+
- {{ $gv.TypeForKind . | markdownRenderTypeLink }}
1213
{{- end }}
1314
{{ end }}
1415

‎hack/api-docs/templates/gv_list.tpl‎

Lines changed: 12 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,20 @@
11
{{- define "gvList" -}}
22
{{- $groupVersions := . -}}
3+
---
4+
mapped_pages:
5+
- https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-api-reference.html
6+
navigation_title: API Reference
7+
applies_to:
8+
deployment:
9+
eck: all
10+
---
11+
% Generated documentation. Please do not edit.
312

4-
// Generated documentation. Please do not edit.
5-
:page_id: api-reference
6-
:anchor_prefix: k8s-api
13+
# {{`{{eck}}`}} API Reference [k8s-api-reference]
714

8-
ifdef::env-github[]
9-
****
10-
link:https://www.elastic.co/guide/en/cloud-on-k8s/master/k8s-{page_id}.html[View this document on the Elastic website]
11-
****
12-
endif::[]
13-
14-
[id="{p}-{page_id}"]
15-
= API Reference
16-
17-
.Packages
15+
## Packages
1816
{{- range $groupVersions }}
19-
- {{ asciidocRenderGVLink . }}
17+
* {{ markdownRenderGVLink . }}
2018
{{- end }}
2119

2220
{{ range $groupVersions }}

‎hack/api-docs/templates/type.tpl‎

Lines changed: 11 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,31 @@
11
{{- define "type" -}}
22
{{- $type := . -}}
3-
{{- if asciidocShouldRenderType $type -}}
3+
{{- if markdownShouldRenderType $type -}}
44

5-
[id="{{ asciidocTypeID $type | asciidocRenderAnchorID }}"]
6-
=== {{ $type.Name }} {{ if $type.IsAlias }}({{ asciidocRenderTypeLink $type.UnderlyingType }}) {{ end }}
5+
### {{ $type.Name }} {{ if $type.IsAlias }}({{ markdownRenderTypeLink $type.UnderlyingType }}) {{ end }} [#{{ $type.Name | lower }}]
76

87
{{ $type.Doc }}
98

109
{{ if $type.References -}}
11-
.Appears In:
12-
****
10+
:::{admonition} Appears In:
1311
{{- range $type.SortedReferences }}
14-
- {{ asciidocRenderTypeLink . }}
12+
* {{ markdownRenderTypeLink . }}
1513
{{- end }}
16-
****
14+
15+
:::
1716
{{- end }}
1817

1918
{{ if $type.Members -}}
20-
[cols="25a,75a", options="header"]
21-
|===
22-
| Field | Description
19+
| Field | Description |
20+
| --- | --- |
2321
{{ if $type.GVK -}}
24-
| *`apiVersion`* __string__ | `{{ $type.GVK.Group }}/{{ $type.GVK.Version }}`
25-
| *`kind`* __string__ | `{{ $type.GVK.Kind }}`
22+
| *`apiVersion`* __string__ | `{{ $type.GVK.Group }}/{{ $type.GVK.Version }}` |
23+
| *`kind`* __string__ | `{{ $type.GVK.Kind }}` |
2624
{{ end -}}
2725

2826
{{ range $type.Members -}}
29-
| *`{{ .Name }}`* __{{ asciidocRenderType .Type }}__ | {{ template "type_members" . }}
27+
| *`{{ .Name }}`* __{{ markdownRenderType .Type }}__ | {{ template "type_members" . }} |
3028
{{ end -}}
31-
|===
3229
{{ end -}}
3330

3431
{{- end -}}

‎hack/api-docs/templates/type_members.tpl‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
{{- $field := . -}}
33
{{- if eq $field.Name "metadata" -}}
44
Refer to Kubernetes API documentation for fields of `metadata`.
5-
{{ else -}}
6-
{{ $field.Doc }}
5+
{{- else -}}
6+
{{ $field.Doc | replace "\n" "<br>" }}
77
{{- end -}}
88
{{- end -}}

0 commit comments

Comments
 (0)