Skip to content

Commit c370470

Browse files
fcanovaifcanovai
authored
docs: generate pure markdown documentation (#251)
Switch to building documentation in markdown, avoiding the markdown+html hybrid we have. Closes #250 Signed-off-by: Francesco Canovai <[email protected]>
1 parent 898b569 commit c370470

File tree

11 files changed

+207
-289
lines changed

11 files changed

+207
-289
lines changed

‎Taskfile.yml‎

Lines changed: 16 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,7 @@ tasks:
5858
desc: Check for uncommitted changes
5959
deps:
6060
- manifest-main
61+
- apidoc
6162
env:
6263
# renovate: datasource=git-refs depName=uncommitted lookupName=https://github.com/cloudnative-pg/daggerverse currentValue=main
6364
DAGGER_UNCOMMITTED_SHA: db65290569cb7723a32e72fcfb134668e7b998c8
@@ -68,17 +69,26 @@ tasks:
6869

6970
apidoc:
7071
desc: Update the API Reference section of the documentation
72+
deps:
73+
- controller-gen
7174
env:
72-
# renovate: datasource=git-refs depName=genref lookupName=https://github.com/cloudnative-pg/daggerverse currentValue=main
73-
DAGGER_APIDOC_SHA: db65290569cb7723a32e72fcfb134668e7b998c8
75+
# renovate: datasource=git-refs depName=crd-gen-refs lookupName=https://github.com/cloudnative-pg/daggerverse currentValue=main
76+
DAGGER_CRDGENREF_SHA: ba865842d907910c469d016c3ecfa009e4c66915
7477
cmds:
75-
- GITHUB_REF= dagger -s call -m github.com/cloudnative-pg/daggerverse/genref@${DAGGER_APIDOC_SHA} genref --source .
76-
--args "-c=config.yaml" --args "-o=src" --args "-include=plugin-barman-cloud"
77-
file --path src/plugin-barman-cloud.v1.md
78+
- >
79+
GITHUB_REF= dagger -s call -m github.com/cloudnative-pg/daggerverse/crd-ref-docs@${DAGGER_CRDGENREF_SHA} generate
80+
--src .
81+
--source-path api/v1
82+
--config-file docs/config.yaml
83+
--renderer markdown
84+
--templates-dir docs/markdown
85+
file --path out.md
7886
export --path docs/src/plugin-barman-cloud.v1.md
7987
sources:
8088
- ./api/**/*.go
8189
- ./docs/config.yaml
90+
- ./docs/markdown/**/*.tpl
91+
- ./Taskfile.yml
8292
generates:
8393
- ./docs/src/plugin-barman-cloud.v1.md
8494

@@ -338,6 +348,7 @@ tasks:
338348
339349
controller-gen:
340350
desc: Run controller-gen
351+
run: once
341352
env:
342353
# renovate: datasource=git-refs depName=controller-gen lookupName=https://github.com/cloudnative-pg/daggerverse currentValue=main
343354
DAGGER_CONTROLLER_GEN_SHA: db65290569cb7723a32e72fcfb134668e7b998c8

‎api/v1/groupversion_info.go‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,6 @@ See the License for the specific language governing permissions and
1414
limitations under the License.
1515
*/
1616

17-
// Package v1 contains API Schema definitions for the barmancloud v1 API group
18-
// +kubebuilder:object:generate=true
19-
// +groupName=barmancloud.cnpg.io
2017
package v1
2118

2219
import (

‎docs/config.yaml‎

Lines changed: 19 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,20 @@
1-
hiddenMemberFields:
2-
- "TypeMeta"
1+
processor:
2+
ignoreGroupVersions:
3+
- "GVK"
4+
customMarkers:
5+
- name: "optional"
6+
target: field
7+
ignoreFields:
8+
# - "status$"
9+
- "TypeMeta$"
10+
ignoreTypes:
11+
- "ObjectStoreList$"
312

4-
externalPackages:
5-
- match: ^k8s\.io/(api|apimachinery/pkg/apis)/
6-
target: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#{{- lower .TypeIdentifier -}}-{{- arrIndex .PackageSegments -1 -}}-{{- arrIndex .PackageSegments -2 -}}
7-
- match: ^github\.com/cloudnative-pg/barman-cloud
8-
target: https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api/#{{- .TypeIdentifier }}
9-
10-
hideTypePatterns:
11-
- "ParseError$"
12-
- "\\.ObjectStoreList$"
13-
14-
markdownDisabled: false
15-
16-
stripPrefix:
17-
- k8s.io/api/
18-
- k8s.io/apimachinery/pkg/apis/
19-
20-
apis:
21-
- name: plugin-barman-cloud
22-
title: API Reference
23-
package: github.com/cloudnative-pg/plugin-barman-cloud
24-
path: api/v1
13+
render:
14+
# Version of Kubernetes to use when generating links to Kubernetes API documentation.
15+
# renovate: datasource=git-refs depName=kubernetes/kubernetes lookupName=https://github.com/kubernetes/kubernetes
16+
kubernetesVersion: 1.31
17+
knownTypes:
18+
- name: BarmanObjectStoreConfiguration
19+
package: github.com/cloudnative-pg/barman-cloud/pkg/api
20+
link: https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#BarmanObjectStoreConfiguration

‎docs/markdown/gv_details.tpl‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
{{- define "gvDetails" -}}
2+
{{- $gv := . -}}
3+
4+
## {{ $gv.GroupVersionString }}
5+
6+
{{ $gv.Doc }}
7+
8+
{{- if $gv.Kinds }}
9+
### Resource Types
10+
{{- range $gv.SortedKinds }}
11+
- {{ $gv.TypeForKind . | markdownRenderTypeLink }}
12+
{{- end }}
13+
{{ end }}
14+
15+
{{ range $gv.SortedTypes }}
16+
{{ template "type" . }}
17+
{{ end }}
18+
19+
{{- end -}}

‎docs/markdown/gv_list.tpl‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{{- define "gvList" -}}
2+
{{- $groupVersions := . -}}
3+
4+
# API Reference
5+
6+
## Packages
7+
{{- range $groupVersions }}
8+
- {{ markdownRenderGVLink . }}
9+
{{- end }}
10+
11+
{{ range $groupVersions }}
12+
{{ template "gvDetails" . }}
13+
{{ end }}
14+
15+
{{- end -}}

‎docs/markdown/members.tpl‎

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

‎docs/markdown/pkg.tpl‎

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

‎docs/markdown/type.tpl‎

Lines changed: 42 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,49 @@
1-
{{ define "type" }}
1+
{{- define "type" -}}
2+
{{- $type := . -}}
3+
{{- if markdownShouldRenderType $type -}}
24

3-
## {{ .Name.Name }} {#{{ .Anchor }}}
5+
#### {{ $type.Name }}
46

5-
{{ if eq .Kind "Alias" -}}
6-
(Alias of `{{ .Underlying }}`)
7-
{{ end }}
7+
{{ if $type.IsAlias }}_Underlying type:_ _{{ markdownRenderTypeLink $type.UnderlyingType }}_{{ end }}
88

9-
{{- with .References }}
10-
**Appears in:**
11-
{{ range . }}
12-
{{ if or .Referenced .IsExported -}}
13-
- [{{ .DisplayName }}]({{ .Link }})
14-
{{ end -}}
15-
{{- end -}}
9+
{{ $type.Doc }}
10+
11+
{{ if $type.Validation -}}
12+
_Validation:_
13+
{{- range $type.Validation }}
14+
- {{ . }}
1615
{{- end }}
16+
{{- end }}
17+
18+
{{ if $type.References -}}
19+
_Appears in:_
20+
{{- range $type.SortedReferences }}
21+
- {{ markdownRenderTypeLink . }}
22+
{{- end }}
23+
{{- end }}
24+
25+
{{ if $type.Members -}}
26+
| Field | Description | Required | Default | Validation |
27+
| --- | --- | --- | --- | --- |
28+
{{ if $type.GVK -}}
29+
| `apiVersion` _string_ | `{{ $type.GVK.Group }}/{{ $type.GVK.Version }}` | True | | |
30+
| `kind` _string_ | `{{ $type.GVK.Kind }}` | True | | |
31+
{{ end -}}
32+
33+
{{ range $type.Members -}}
34+
| `{{ .Name }}` _{{ markdownRenderType .Type }}_ | {{ template "type_members" . }} | {{ if not .Markers.optional -}}True{{- end }} | {{ markdownRenderDefault .Default }} | {{ range .Validation -}} {{ markdownRenderFieldDoc . }} <br />{{ end }} |
35+
{{ end -}}
36+
37+
{{ end -}}
38+
39+
{{ if $type.EnumValues -}}
40+
| Field | Description |
41+
| --- | --- |
42+
{{ range $type.EnumValues -}}
43+
| `{{ .Name }}` | {{ markdownRenderFieldDoc .Doc }} |
44+
{{ end -}}
45+
{{ end -}}
46+
1747

18-
{{ if .GetComment -}}
19-
{{ .GetComment }}
20-
{{ end }}
21-
{{ if .GetMembers -}}
22-
<table class="table">
23-
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
24-
<tbody>
25-
{{- /* . is a apiType */ -}}
26-
{{- if .IsExported -}}
27-
{{- /* Add apiVersion and kind rows if deemed necessary */}}
28-
<tr><td><code>apiVersion</code> <B>[Required]</B><br/>string</td><td><code>{{- .APIGroup -}}</code></td></tr>
29-
<tr><td><code>kind</code> <B>[Required]</B><br/>string</td><td><code>{{- .Name.Name -}}</code></td></tr>
30-
{{- end -}}
31-
32-
{{/* The actual list of members is in the following template */}}
33-
{{- template "members" . -}}
34-
</tbody>
35-
</table>
3648
{{- end -}}
3749
{{- end -}}

‎docs/markdown/type_members.tpl‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{{- define "type_members" -}}
2+
{{- $field := . -}}
3+
{{- if eq $field.Name "metadata" -}}
4+
Refer to Kubernetes API documentation for fields of `metadata`.
5+
{{- else -}}
6+
{{ markdownRenderFieldDoc $field.Doc }}
7+
{{- end -}}
8+
{{- end -}}

0 commit comments

Comments
 (0)