Skip to content

Commit 9725f26

Browse files
kcp-ci-botkcp-ci-bot
authored
Merge pull request #70 from kcp-dev/api-docs
generate docs for our CRDs
2 parents bc68162 + fe21a52 commit 9725f26

File tree

11 files changed

+227
-8
lines changed

11 files changed

+227
-8
lines changed

‎.github/workflows/docs-gen-and-push.yaml

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
name: Generate and push docs
1+
name: Documentation
22

33
on:
44
# So we can trigger manually if needed
@@ -24,7 +24,7 @@ concurrency:
2424

2525
jobs:
2626
generate-and-push:
27-
name: Generate and push docs
27+
name: Generate and push
2828
runs-on: ubuntu-latest
2929
steps:
3030
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # tag=v4.2.2
@@ -42,4 +42,10 @@ jobs:
4242
python-version: '3.10'
4343
cache: 'pip'
4444

45-
- run: make deploy-docs
45+
# mike does not support giving CLI flags for mkdocs, but we also do not
46+
# want to permanently enable strict mode, so here we enable it just for this
47+
# task
48+
- run: |
49+
echo "strict: true" >> docs/mkdocs.yml
50+
51+
- run: make generate-api-docs deploy-docs

‎Makefile

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -154,6 +154,11 @@ verify:
154154
VENVDIR=$(abspath docs/venv)
155155
REQUIREMENTS_TXT=docs/requirements.txt
156156

157+
.PHONY: generate-api-docs
158+
generate-api-docs: ## Generate api docs
159+
git clean -fdX docs/content/reference
160+
docs/generators/crd-ref/run-crd-ref-gen.sh
161+
157162
.PHONY: local-docs
158163
local-docs: venv ## Run mkdocs serve
159164
. $(VENV)/activate; \

‎docs/content/.pages

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,5 @@ nav:
44
- Publishing Resources: publish-resources
55
- Consuming Services: consuming-services.md
66
- FAQ: faq.md
7+
- Reference: reference
78
- Contributing: contributing

‎docs/content/reference/.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
crd/

‎docs/content/reference/.pages

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
nav:
2+
- index.md
3+
- CRD: crd

‎docs/content/reference/index.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Reference
2+
3+
This chapter provides automatically generated references for the APIs provided by the kcp Sync Agent.

‎docs/generators/crd-ref/config.yaml

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Copyright 2021 The KCP Authors.
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
template_path: ./crd.template.md
16+
17+
source_repositories:
18+
- url: https://github.com/kcp-dev/api-syncagent
19+
organization: kcp-dev
20+
short_name: api-syncagent
21+
commit_reference: main
22+
crd_paths:
23+
- deploy/crd
24+
cr_paths:
25+
- docs/cr
26+
metadata:
27+
publishedresources.syncagent.kcp.io:
28+
owner:
29+
- https://github.com/kcp-dev/api-syncagent

‎docs/generators/crd-ref/crd.template.md

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
---
2+
title: {{ .Title }}
3+
description: |
4+
{{- if .Description }}
5+
{{ .Description | indent 2 }}
6+
{{- else }}
7+
Custom resource definition (CRD) schema reference page for the {{ .Title }}
8+
resource ({{ .NamePlural }}.{{ .Group }}), as part of the Giant Swarm
9+
Management API documentation.
10+
{{- end }}
11+
weight: {{ .Weight }}
12+
---
13+
14+
{{- with .Metadata.Deprecation }}
15+
{{ "{{" }}% pageinfo color="warning" %{{ "}}"}}
16+
{{- with .Info }}
17+
{{ . }}
18+
{{- end }}
19+
{{- with .ReplacedBy }}
20+
This CRD is being replaced by <a href="../{{ .FullName }}/">{{ .ShortName }}</a>.
21+
{{- end }}
22+
{{"{{% /pageinfo %}}"}}
23+
{{- end }}
24+
25+
## {{ .Title }} CRD schema reference (group {{ .Group }})
26+
<div class="lead">{{`{{`}} page.meta.description {{`}}`}}</div>
27+
28+
<dl class="crd-meta">
29+
<dt class="fullname">Full name:</dt>
30+
<dd class="fullname">{{ .NamePlural }}.{{ .Group }}</dd>
31+
<dt class="groupname">Group:</dt>
32+
<dd class="groupname">{{ .Group }}</dd>
33+
<dt class="singularname">Singular name:</dt>
34+
<dd class="singularname">{{ .NameSingular }}</dd>
35+
<dt class="pluralname">Plural name:</dt>
36+
<dd class="pluralname">{{ .NamePlural }}</dd>
37+
<dt class="scope">Scope:</dt>
38+
<dd class="scope">{{ .Scope }}</dd>
39+
<dt class="versions">Versions:</dt>
40+
<dd class="versions">
41+
{{- range .Versions -}}
42+
<a class="version" href="#{{.}}" title="Show schema for version {{.}}">{{.}}</a>
43+
{{- end -}}
44+
</dd>
45+
</dl>
46+
47+
{{ if .VersionSchemas }}
48+
{{ $versionSchemas := .VersionSchemas }}
49+
{{ range .Versions -}}
50+
{{ $versionName := . -}}
51+
{{ $versionSchema := (index $versionSchemas $versionName) -}}
52+
<div class="crd-schema-version">
53+
<h2 id="{{$versionName}}">Version {{$versionName}}</h2>
54+
55+
{{ with $versionSchema.ExampleCR }}
56+
<h3 id="crd-example-{{$versionName}}">Example CR</h3>
57+
58+
```yaml
59+
{{ .|raw -}}
60+
```
61+
62+
{{end}}
63+
64+
<h3 id="property-details-{{$versionName}}">Properties</h3>
65+
66+
{{ range $versionSchema.Properties }}
67+
<div class="property depth-{{.Depth}}">
68+
<div class="property-header">
69+
<h3 class="property-path" id="{{$versionName}}-{{.Path}}">{{.Path}}</h3>
70+
</div>
71+
<div class="property-body">
72+
<div class="property-meta">
73+
{{with .Type}}<span class="property-type">{{.}}</span>{{end}}
74+
{{ if not .Required }}
75+
{{ else -}}
76+
<span class="property-required">Required</span>
77+
{{ end -}}
78+
</div>
79+
{{with .Description}}
80+
<div class="property-description">
81+
{{.|markdown}}
82+
</div>
83+
{{end}}
84+
</div>
85+
</div>
86+
{{ end }}
87+
88+
{{ if $versionSchema.Annotations }}
89+
<h3 id="annotation-details-{{$versionName}}">Annotations</h3>
90+
91+
{{ range $versionSchema.Annotations }}
92+
<div class="annotation">
93+
<div class="annotation-header">
94+
<h3 class="annotation-path" id="{{.CRDVersion}}-{{.Annotation}}">{{.Annotation}}</h3>
95+
</div>
96+
<div class="annotation-body">
97+
<div class="annotation-meta">
98+
{{with .Release}}<span class="annotation-release">{{.}}</span>{{end}}
99+
</div>
100+
{{with .Documentation}}
101+
<div class="annotation-description">
102+
{{.|markdown}}
103+
</div>
104+
{{end}}
105+
</div>
106+
</div>
107+
{{ end }}
108+
{{ end }}
109+
110+
</div>
111+
{{end}}
112+
113+
{{ else }}
114+
<div class="crd-noversions">
115+
<p>We currently cannot show any schema information on this <abbr title="custom resource definition">CRD</abbr>. Sorry for the inconvenience!</p>
116+
<p>Please refer to the <a href="https://pkg.go.dev/github.com/giantswarm/apiextensions/pkg/apis/">Godoc</a> or <a href="https://github.com/giantswarm/apiextensions/tree/master/pkg/apis">source</a> for details.</p>
117+
</div>
118+
{{ end }}

‎docs/generators/crd-ref/run-crd-ref-gen.sh

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
#!/usr/bin/env bash
2+
3+
# Copyright 2021 The KCP Authors.
4+
#
5+
# Licensed under the Apache License, Version 2.0 (the "License");
6+
# you may not use this file except in compliance with the License.
7+
# You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing, software
12+
# distributed under the License is distributed on an "AS IS" BASIS,
13+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
# See the License for the specific language governing permissions and
15+
# limitations under the License.
16+
17+
set -euo pipefail
18+
19+
REPO_ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)
20+
21+
CONTAINER_ENGINE=${CONTAINER_ENGINE:-podman}
22+
CRD_DOCS_GENERATOR_VERSION=0.11.4
23+
24+
DESTINATION="${REPO_ROOT}/docs/content/reference/crd"
25+
mkdir -p "${DESTINATION}"
26+
27+
BIND_MOUNT_OPTS=":z"
28+
if [[ $(uname -s) == "Darwin" ]]; then
29+
BIND_MOUNT_OPTS=""
30+
fi
31+
32+
# Generate new content
33+
$CONTAINER_ENGINE run \
34+
--rm \
35+
-v "${DESTINATION}":/opt/crd-docs-generator/output"${BIND_MOUNT_OPTS}" \
36+
-v "${REPO_ROOT}"/docs/generators/crd-ref:/opt/crd-docs-generator/config"${BIND_MOUNT_OPTS}" \
37+
"quay.io/giantswarm/crd-docs-generator:${CRD_DOCS_GENERATOR_VERSION}" \
38+
--config /opt/crd-docs-generator/config/config.yaml
39+
40+
# Organise CRDs by API group
41+
for file in ${DESTINATION}/*.md; do
42+
filename="$(basename $file)"
43+
apigroup="$(basename $filename .md | cut -d. -f2-)"
44+
crdname="$(basename $filename .md | cut -d. -f1)"
45+
46+
mkdir -p "${DESTINATION}/${apigroup}"
47+
mv "${file}" "${DESTINATION}/${apigroup}/${crdname}.md"
48+
done
49+
50+
# Generate a .pages config file to override title case being applied to
51+
# folder names by default (https://github.com/mkdocs/mkdocs/issues/2086)
52+
echo "nav:" > "${DESTINATION}/.pages"
53+
for dir in ${DESTINATION}/*/; do
54+
apigroup="$(basename $dir)"
55+
echo " - ${apigroup}: ${apigroup}" >> "${DESTINATION}/.pages"
56+
done

‎docs/requirements.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
mike==2.1.3
22
mkdocs==1.5.3
33
mkdocs-awesome-pages-plugin==2.9.2
4-
mkdocs-macros-plugin==1.0.5
4+
mkdocs-macros-plugin==1.3.7
55
mkdocs-material==9.5.17
66
mkdocs-material-extensions==1.3.1
77
mkdocs-static-i18n==1.2.2

‎docs/scripts/deploy-docs.sh

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,7 @@
1414
# See the License for the specific language governing permissions and
1515
# limitations under the License.
1616

17-
set -o errexit
18-
set -o nounset
19-
set -o pipefail
20-
set -o xtrace
17+
set -euo pipefail
2118

2219
REPO_ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)
2320
cd "$REPO_ROOT/docs"

0 commit comments

Comments
 (0)