diff --git a/.github/workflows/docs-gen-and-push.yaml b/.github/workflows/docs-gen-and-push.yaml index 4cfc0aa..11bf96a 100644 --- a/.github/workflows/docs-gen-and-push.yaml +++ b/.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 diff --git a/Makefile b/Makefile index c8528ad..7ad46d9 100644 --- a/Makefile +++ b/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; \ diff --git a/docs/content/.pages b/docs/content/.pages index 830682c..aba5f84 100644 --- a/docs/content/.pages +++ b/docs/content/.pages @@ -4,4 +4,5 @@ nav: - Publishing Resources: publish-resources - Consuming Services: consuming-services.md - FAQ: faq.md + - Reference: reference - Contributing: contributing diff --git a/docs/content/reference/.gitignore b/docs/content/reference/.gitignore new file mode 100644 index 0000000..fb4e233 --- /dev/null +++ b/docs/content/reference/.gitignore @@ -0,0 +1 @@ +crd/ diff --git a/docs/content/reference/.pages b/docs/content/reference/.pages new file mode 100644 index 0000000..561adb2 --- /dev/null +++ b/docs/content/reference/.pages @@ -0,0 +1,3 @@ +nav: + - index.md + - CRD: crd diff --git a/docs/content/reference/index.md b/docs/content/reference/index.md new file mode 100644 index 0000000..b802c5f --- /dev/null +++ b/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. diff --git a/docs/generators/crd-ref/config.yaml b/docs/generators/crd-ref/config.yaml new file mode 100644 index 0000000..01462b4 --- /dev/null +++ b/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 diff --git a/docs/generators/crd-ref/crd.template.md b/docs/generators/crd-ref/crd.template.md new file mode 100644 index 0000000..7ac1aa5 --- /dev/null +++ b/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 {{ .ShortName }}. +{{- end }} +{{"{{% /pageinfo %}}"}} +{{- end }} + +## {{ .Title }} CRD schema reference (group {{ .Group }}) +
{{`{{`}} page.meta.description {{`}}`}}
+ +
+
Full name:
+
{{ .NamePlural }}.{{ .Group }}
+
Group:
+
{{ .Group }}
+
Singular name:
+
{{ .NameSingular }}
+
Plural name:
+
{{ .NamePlural }}
+
Scope:
+
{{ .Scope }}
+
Versions:
+
+{{- range .Versions -}} +{{.}} +{{- end -}} +
+
+ +{{ if .VersionSchemas }} +{{ $versionSchemas := .VersionSchemas }} +{{ range .Versions -}} +{{ $versionName := . -}} +{{ $versionSchema := (index $versionSchemas $versionName) -}} +
+

Version {{$versionName}}

+ +{{ with $versionSchema.ExampleCR }} +

Example CR

+ +```yaml +{{ .|raw -}} +``` + +{{end}} + +

Properties

+ +{{ range $versionSchema.Properties }} +
+
+

{{.Path}}

+
+
+
+{{with .Type}}{{.}}{{end}} +{{ if not .Required }} +{{ else -}} +Required +{{ end -}} +
+{{with .Description}} +
+{{.|markdown}} +
+{{end}} +
+
+{{ end }} + +{{ if $versionSchema.Annotations }} +

Annotations

+ +{{ range $versionSchema.Annotations }} +
+
+

{{.Annotation}}

+
+
+
+{{with .Release}}{{.}}{{end}} +
+{{with .Documentation}} +
+{{.|markdown}} +
+{{end}} +
+
+{{ end }} +{{ end }} + +
+{{end}} + +{{ else }} +
+

We currently cannot show any schema information on this CRD. Sorry for the inconvenience!

+

Please refer to the Godoc or source for details.

+
+{{ end }} diff --git a/docs/generators/crd-ref/run-crd-ref-gen.sh b/docs/generators/crd-ref/run-crd-ref-gen.sh new file mode 100755 index 0000000..baa9b63 --- /dev/null +++ b/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 diff --git a/docs/requirements.txt b/docs/requirements.txt index 28d6ef2..d26c143 100644 --- a/docs/requirements.txt +++ b/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 diff --git a/docs/scripts/deploy-docs.sh b/docs/scripts/deploy-docs.sh index 9af0a7d..29692c5 100755 --- a/docs/scripts/deploy-docs.sh +++ b/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"