generate docs for our CRDs

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

@@ -1,4 +1,4 @@
-name: Generate and push docs
+name: Documentation
 
 on:
   # So we can trigger manually if needed
@@ -24,7 +24,7 @@ concurrency:
 
 jobs:
   generate-and-push:
-    name: Generate and push docs
+    name: Generate and push
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # tag=v4.2.2
@@ -42,4 +42,10 @@ jobs:
           python-version: '3.10'
           cache: 'pip'
 
-      - run: make deploy-docs
+      # mike does not support giving CLI flags for mkdocs, but we also do not
+      # want to permanently enable strict mode, so here we enable it just for this
+      # task
+      - run: |
+          echo "strict: true" >> docs/mkdocs.yml
+
+      - run: make generate-api-docs deploy-docs

Makefile

@@ -154,6 +154,11 @@ verify:
 VENVDIR=$(abspath docs/venv)
 REQUIREMENTS_TXT=docs/requirements.txt
 
+.PHONY: generate-api-docs
+generate-api-docs: ## Generate api docs
+	git clean -fdX docs/content/reference
+	docs/generators/crd-ref/run-crd-ref-gen.sh
+
 .PHONY: local-docs
 local-docs: venv ## Run mkdocs serve
 	. $(VENV)/activate; \

docs/content/.pages

@@ -4,4 +4,5 @@ nav:
   - Publishing Resources: publish-resources
   - Consuming Services: consuming-services.md
   - FAQ: faq.md
+  - Reference: reference
   - Contributing: contributing

docs/content/reference/.gitignore

@@ -0,0 +1 @@
+crd/

docs/content/reference/.pages

@@ -0,0 +1,3 @@
+nav:
+    - index.md
+    - CRD: crd

docs/content/reference/index.md

@@ -0,0 +1,3 @@
+# Reference
+
+This chapter provides automatically generated references for the APIs provided by the kcp Sync Agent.

docs/generators/crd-ref/config.yaml

@@ -0,0 +1,29 @@
+# Copyright 2021 The KCP Authors.
+#
+# Licensed 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.
+
+template_path: ./crd.template.md
+
+source_repositories:
+  - url: https://github.com/kcp-dev/api-syncagent
+    organization: kcp-dev
+    short_name: api-syncagent
+    commit_reference: main
+    crd_paths:
+      - deploy/crd
+    cr_paths:
+      - docs/cr
+    metadata:
+      publishedresources.syncagent.kcp.io:
+        owner:
+          - https://github.com/kcp-dev/api-syncagent

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

@@ -0,0 +1,118 @@
+---
+title: {{ .Title }}
+description: |
+{{- if .Description }}
+{{ .Description | indent 2 }}
+{{- else }}
+  Custom resource definition (CRD) schema reference page for the {{ .Title }} 
+  resource ({{ .NamePlural }}.{{ .Group }}), as part of the Giant Swarm 
+  Management API documentation.
+{{- end }}
+weight: {{ .Weight }}
+---
+
+{{- with .Metadata.Deprecation }}
+{{ "{{" }}% pageinfo color="warning" %{{ "}}"}}
+{{- with .Info }}
+{{ . }}
+{{- end }}
+{{- with .ReplacedBy }}
+This CRD is being replaced by <a href="../{{ .FullName }}/">{{ .ShortName }}</a>.
+{{- end }}
+{{"{{% /pageinfo %}}"}}
+{{- end }}
+
+## {{ .Title }} CRD schema reference (group {{ .Group }})
+<div class="lead">{{`{{`}} page.meta.description {{`}}`}}</div>
+
+<dl class="crd-meta">
+<dt class="fullname">Full name:</dt>
+<dd class="fullname">{{ .NamePlural }}.{{ .Group }}</dd>
+<dt class="groupname">Group:</dt>
+<dd class="groupname">{{ .Group }}</dd>
+<dt class="singularname">Singular name:</dt>
+<dd class="singularname">{{ .NameSingular }}</dd>
+<dt class="pluralname">Plural name:</dt>
+<dd class="pluralname">{{ .NamePlural }}</dd>
+<dt class="scope">Scope:</dt>
+<dd class="scope">{{ .Scope }}</dd>
+<dt class="versions">Versions:</dt>
+<dd class="versions">
+{{- range .Versions -}}
+<a class="version" href="#{{.}}" title="Show schema for version {{.}}">{{.}}</a>
+{{- end -}}
+</dd>
+</dl>
+
+{{ if .VersionSchemas }}
+{{ $versionSchemas := .VersionSchemas }}
+{{ range .Versions -}}
+{{ $versionName := . -}}
+{{ $versionSchema := (index $versionSchemas $versionName) -}}
+<div class="crd-schema-version">
+<h2 id="{{$versionName}}">Version {{$versionName}}</h2>
+
+{{ with $versionSchema.ExampleCR }}
+<h3 id="crd-example-{{$versionName}}">Example CR</h3>
+
+```yaml
+{{ .|raw -}}
+```
+
+{{end}}
+
+<h3 id="property-details-{{$versionName}}">Properties</h3>
+
+{{ range $versionSchema.Properties }}
+<div class="property depth-{{.Depth}}">
+<div class="property-header">
+<h3 class="property-path" id="{{$versionName}}-{{.Path}}">{{.Path}}</h3>
+</div>
+<div class="property-body">
+<div class="property-meta">
+{{with .Type}}<span class="property-type">{{.}}</span>{{end}}
+{{ if not .Required }}
+{{ else -}}
+<span class="property-required">Required</span>
+{{ end -}}
+</div>
+{{with .Description}}
+<div class="property-description">
+{{.|markdown}}
+</div>
+{{end}}
+</div>
+</div>
+{{ end }}
+
+{{ if $versionSchema.Annotations }}
+<h3 id="annotation-details-{{$versionName}}">Annotations</h3>
+
+{{ range $versionSchema.Annotations }}
+<div class="annotation">
+<div class="annotation-header">
+<h3 class="annotation-path" id="{{.CRDVersion}}-{{.Annotation}}">{{.Annotation}}</h3>
+</div>
+<div class="annotation-body">
+<div class="annotation-meta">
+{{with .Release}}<span class="annotation-release">{{.}}</span>{{end}}
+</div>
+{{with .Documentation}}
+<div class="annotation-description">
+{{.|markdown}}
+</div>
+{{end}}
+</div>
+</div>
+{{ end }}
+{{ end }}
+
+</div>
+{{end}}
+
+{{ else }}
+<div class="crd-noversions">
+<p>We currently cannot show any schema information on this <abbr title="custom resource definition">CRD</abbr>. Sorry for the inconvenience!</p>
+<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>
+</div>
+{{ end }}

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

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+
+# Copyright 2021 The KCP Authors.
+#
+# Licensed 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.
+
+set -euo pipefail
+
+REPO_ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)
+
+CONTAINER_ENGINE=${CONTAINER_ENGINE:-podman}
+CRD_DOCS_GENERATOR_VERSION=0.11.4
+
+DESTINATION="${REPO_ROOT}/docs/content/reference/crd"
+mkdir -p "${DESTINATION}"
+
+BIND_MOUNT_OPTS=":z"
+if [[ $(uname -s) == "Darwin" ]]; then
+  BIND_MOUNT_OPTS=""
+fi
+
+# Generate new content
+$CONTAINER_ENGINE run \
+  --rm \
+  -v "${DESTINATION}":/opt/crd-docs-generator/output"${BIND_MOUNT_OPTS}" \
+  -v "${REPO_ROOT}"/docs/generators/crd-ref:/opt/crd-docs-generator/config"${BIND_MOUNT_OPTS}" \
+  "quay.io/giantswarm/crd-docs-generator:${CRD_DOCS_GENERATOR_VERSION}" \
+  --config /opt/crd-docs-generator/config/config.yaml
+
+# Organise CRDs by API group
+for file in ${DESTINATION}/*.md; do
+  filename="$(basename $file)"
+  apigroup="$(basename $filename .md | cut -d. -f2-)"
+  crdname="$(basename $filename .md | cut -d. -f1)"
+
+  mkdir -p "${DESTINATION}/${apigroup}"
+  mv "${file}" "${DESTINATION}/${apigroup}/${crdname}.md"
+done
+
+# Generate a .pages config file to override title case being applied to
+# folder names by default (https://github.com/mkdocs/mkdocs/issues/2086)
+echo "nav:" > "${DESTINATION}/.pages"
+for dir in ${DESTINATION}/*/; do
+  apigroup="$(basename $dir)"
+  echo "  - ${apigroup}: ${apigroup}" >> "${DESTINATION}/.pages"
+done

docs/requirements.txt

@@ -1,7 +1,7 @@
 mike==2.1.3
 mkdocs==1.5.3
 mkdocs-awesome-pages-plugin==2.9.2
-mkdocs-macros-plugin==1.0.5
+mkdocs-macros-plugin==1.3.7
 mkdocs-material==9.5.17
 mkdocs-material-extensions==1.3.1
 mkdocs-static-i18n==1.2.2

docs/scripts/deploy-docs.sh

@@ -14,10 +14,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-set -o errexit
-set -o nounset
-set -o pipefail
-set -o xtrace
+set -euo pipefail
 
 REPO_ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)
 cd "$REPO_ROOT/docs"