Skip to content

Commit 17c5e9c

Browse files
avinalavinal
committed
add github actions to build and deploy hugo docs
This GitHub Actions does the following: - generates CLI docs - generates CRD refs - saves new tags as archive in gh-pages branch for doc versioning - builds and deploys hugo docs to github pages - fix go version check mistaking hugo-version as go-version Signed-off-by: Avinal Kumar <[email protected]>
1 parent 12bbb4c commit 17c5e9c

File tree

7 files changed

+364
-2
lines changed

7 files changed

+364
-2
lines changed

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

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
name: Generate and push docs
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
tags:
8+
- "v*"
9+
paths:
10+
- "cmd/**"
11+
- "docs/**"
12+
- "pkg/**"
13+
- "README.md"
14+
workflow_dispatch:
15+
16+
jobs:
17+
generate-and-push:
18+
name: Generate and push docs
19+
runs-on: ubuntu-latest
20+
steps:
21+
- uses: actions/checkout@v3
22+
with:
23+
submodules: true # Fetch Hugo themes (true OR recursive)
24+
fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod
25+
path: kcp
26+
- uses: actions/checkout@v3
27+
with:
28+
ref: gh-pages
29+
path: docs
30+
- uses: actions/setup-go@v3
31+
with:
32+
go-version: v1.18
33+
- name: Setup Hugo
34+
uses: peaceiris/actions-hugo@v2
35+
with:
36+
hugo-version: "0.104.3"
37+
extended: true
38+
39+
# install npm dependencies
40+
- name: Setup Node
41+
uses: actions/setup-node@v2
42+
with:
43+
node-version: "16"
44+
- name: Cache dependencies
45+
uses: actions/cache@v2
46+
with:
47+
path: ~/.npm
48+
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
49+
restore-keys: |
50+
${{ runner.os }}-node-
51+
- name: Install dependencies
52+
- run: cd kcp/docs && npm install && npm ci
53+
54+
- name: Copy readmes
55+
run: tail -n +4 kcp/README.md >> docs/content/en/main/_index.md
56+
57+
- name: Generate CLI and CRD docs
58+
run: cd kcp && make generate-docs
59+
60+
- name: Build hugo docs
61+
run: cd kcp/docs && hugo --minify
62+
63+
# This step check if the trigger is a tag and if so, it will update the version in the
64+
# config.toml file and mark it as archived, since the tag is also a latest main, the same
65+
# content is rebuilt using updated config and folder name. The folder thus generated is saved
66+
# as archive in gh-pages branch.
67+
- name: Update version info on tag for archive
68+
if: startsWith(github.ref, 'refs/tags/v')
69+
run: |
70+
mv kcp/docs/public public
71+
cd kcp/docs
72+
cat <<EOF > temp.txt
73+
#version-start
74+
archived_version = true
75+
version = "${{ github.ref }}"
76+
EOF
77+
ed config.toml<<EOF
78+
/^#version-start
79+
+,/^#version-end/-1d
80+
-r !sed -n '/^#version-start/,/^#version-end/p' temp.txt | grep -v '^#'
81+
w
82+
q
83+
EOF
84+
mv content/en/main content/en/${{ github.ref }}
85+
hugo --minify
86+
rsync -av public/${{ github.ref }} ../../docs
87+
88+
- name: Push to gh-pages on tag for archive
89+
if: startsWith(github.ref, 'refs/tags/v')
90+
run: |
91+
cd docs
92+
git config --local user.name "github-actions[bot]"
93+
git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
94+
git add -A
95+
git commit -m "Static archive of docs for ${{ github.ref }}"
96+
git push
97+
98+
- name: Copy everything from archive to docs
99+
run: rsync -av docs public
100+
101+
- name: Upload build artifact
102+
uses: actions/upload-pages-artifact@v1
103+
with:
104+
path: public/
105+
106+
# Deployment Job
107+
deploy:
108+
environment:
109+
name: github-pages
110+
url: ${{ steps.deployment.outputs.page_url }}
111+
runs-on: ubuntu-22.04
112+
needs: generate-and-push
113+
steps:
114+
- name: Deploy
115+
id: deployment
116+
uses: actions/deploy-pages@v1

‎Makefile‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -140,6 +140,7 @@ update-contextual-logging: $(LOGCHECK)
140140

141141
generate-docs:
142142
go run hack/generate/cli-doc/gen-cli-doc.go
143+
./hack/generate/crd-ref/run-crd-ref-gen.sh
143144

144145
vendor: ## Vendor the dependencies
145146
go mod tidy

‎hack/generate/cli-doc/gen-cli-doc.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ func main() {
3131
log.Fatalf("Failed to get current directory: %v", err)
3232
}
3333

34-
cliDocsPath := filepath.Join(currentDir, "docs", "cli")
34+
cliDocsPath := filepath.Join(currentDir, "docs", "content", "en", "main", "cli")
3535

3636
if err := os.RemoveAll(cliDocsPath); err != nil {
3737
log.Fatalf("Failed to remove existing generated docs: %v", err)

‎hack/generate/crd-ref/config.yaml‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
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/kcp
19+
organization: kcp-dev
20+
short_name: kcp
21+
commit_reference: main
22+
crd_paths:
23+
- config/crds
24+
cr_paths:
25+
- docs/cr
26+
metadata:
27+
apiresourceimports.apiresource.kcp.dev:
28+
owner:
29+
- https://github.com/kcp-dev/kcp
30+
topics:
31+
- apiresource
32+
negotiatedapiresources.apiresource.kcp.dev:
33+
owner:
34+
- https://github.com/kcp-dev/kcp
35+
topics:
36+
- apiresource
37+
apibindings.apis.kcp.dev:
38+
owner:
39+
- https://github.com/kcp-dev/kcp
40+
topics:
41+
- apis
42+
apiexports.apis.kcp.dev:
43+
owner:
44+
- https://github.com/kcp-dev/kcp
45+
topics:
46+
- apis
47+
apiresourceschemas.apis.kcp.dev:
48+
owner:
49+
- https://github.com/kcp-dev/kcp
50+
topics:
51+
- apis
52+
locations.scheduling.kcp.dev:
53+
owner:
54+
- https://github.com/kcp-dev/kcp
55+
topics:
56+
- schuduling
57+
- location
58+
placements.scheduling.kcp.dev:
59+
owner:
60+
- https://github.com/kcp-dev/kcp
61+
topics:
62+
- scheduling
63+
- placements
64+
clusterworkspaces.tenancy.kcp.dev:
65+
owner:
66+
- https://github.com/kcp-dev/kcp
67+
topics:
68+
- tenancy
69+
- workspaces
70+
clusterworkspaceshards.tenancy.kcp.dev:
71+
owner:
72+
- https://github.com/kcp-dev/kcp
73+
topics:
74+
- tenancy
75+
- workspaces
76+
- shards
77+
clusterworkspacetypes.tenancy.kcp.dev:
78+
owner:
79+
- https://github.com/kcp-dev/kcp
80+
topics:
81+
- tenancy
82+
- workspaces
83+
- types
84+
workspaces.tenancy.kcp.dev:
85+
owner:
86+
- https://github.com/kcp-dev/kcp
87+
topics:
88+
- tenancy
89+
- workspaces
90+
synctargets.workload.kcp.dev:
91+
owner:
92+
- https://github.com/kcp-dev/kcp
93+
topics:
94+
- workload
95+
- synctargets

‎hack/generate/crd-ref/crd.template.md‎

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

‎hack/generate/crd-ref/run-crd-ref-gen.sh‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
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 -e
18+
19+
CRD_DOCS_GENERATOR_VERSION=0.10.0
20+
# set destination to crd-reference directory in the docs
21+
DESTINATION="docs/content/en/main/crd-reference"
22+
23+
# Clear output folder
24+
find "${PWD}/${DESTINATION}" -type f -not -name "_index.md" | xargs -I '{}' rm '{}'
25+
26+
# Generate new content
27+
podman run --rm \
28+
-v ${PWD}/${DESTINATION}:/opt/crd-docs-generator/output:z \
29+
-v ${PWD}/hack/generate/crd-ref:/opt/crd-docs-generator/config:z \
30+
quay.io/giantswarm/crd-docs-generator:${CRD_DOCS_GENERATOR_VERSION} \
31+
--config /opt/crd-docs-generator/config/config.yaml

‎hack/verify-go-versions.sh‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ VERSION=$(grep "go 1." go.mod | sed 's/go //')
2121

2222
grep "tag: \"" .ci-operator.yaml | { ! grep -v "${VERSION}"; } || { echo "Wrong go version in .ci-operator.yaml, expected ${VERSION}"; exit 1; }
2323
grep "FROM golang:" Dockerfile | { ! grep -v "${VERSION}"; } || { echo "Wrong go version in Dockerfile, expected ${VERSION}"; exit 1; }
24-
grep "go-version:" .github/workflows/*.yaml | { ! grep -v "go-version: v${VERSION}"; } || { echo "Wrong go version in .github/workflows/*.yaml, expected ${VERSION}"; exit 1; }
24+
grep -w "go-version:" .github/workflows/*.yaml | { ! grep -v "go-version: v${VERSION}"; } || { echo "Wrong go version in .github/workflows/*.yaml, expected ${VERSION}"; exit 1; }
2525
# Note CONTRIBUTING.md isn't copied in the Dockerfile
2626
if [ -e CONTRIBUTING.md ]; then
2727
grep "golang.org/doc/install" CONTRIBUTING.md | { ! grep -v "${VERSION}"; } || { echo "Wrong go version in CONTRIBUTING.md expected ${VERSION}"; exit 1; }

0 commit comments

Comments
 (0)