Skip to content

Commit 1fa33a6

Browse files
build(docs): generate reference pages for Valkey, OpenSearch, Bucket, KubernetesNodes, ComputePlane and Gateway (#756)
Cozystack 1.7 adds Valkey and the ComputePlane module and moves worker pools to KubernetesNodes, while OpenSearch, Bucket and the tenant Gateway module never had a reference page. Their READMEs are generated by cozyvalues-gen and match `values.yaml` at v1.7.0-rc.1, but none of them is in the Makefile lists, so 1.7 docs would ship without them. - `valkey`, `opensearch` and `bucket` go to `APPS` (`applications/`) - `kubernetes-nodes` gets its own list and renders as `kubernetes/kubernetes-nodes.md` in the Kubernetes section - `computeplane` and `gateway` go to `SERVICES` on a separate `SERVICES +=` line, because the `SERVICES` line is next to `NETWORKING` and editing both would conflict Each app gets a front matter template in `next/`. `release-next` copies templates into `v1.7/` and the promote run renders pages from the release ref, so no generated page is committed here. Patch releases of older lines run the same lists against their own tag. Valkey and ComputePlane have no README at v1.6 and v1.5, so `update_apps.sh` would exit 1 on 404 and fail the docs job. For OpenSearch, Bucket, Gateway and KubernetesNodes the old `touch` fallback would write an empty template and a page without front matter into the old tree. Now `update_apps.sh` treats the `_include/<app>.md` template as the list of apps a version documents: app without template is skipped with a warning before anything is fetched or written, app with template but missing README still fails as before. This covers what #728 does with its trunk-only list. I didn't reuse that list because the promote run skips it, `release-next` registers the new version before `update-all` routes to it. Bucket and Gateway pages overlap with hand-written `object-storage/buckets.md` and `networking/gateway-api.md`. I wired them anyway, say if you want them out. The KubernetesNodes commit is separate and easy to drop. Checks: I replayed promote on a copy (`release-next`, then `update-all RELEASE_TAG=v1.7.0 FETCH_REF=v1.7.0-rc.1`), all six pages generate into `v1.7/` and Hugo 0.164.0 preview and production builds pass. `update-all` for v1.6.5 and v1.5.5 passes with six skip warnings and adds no files, with main's script the v1.6 run fails on valkey 404. With http-cache still listed the v1.7.0 run still fails on its 404, so the guard doesn't hide a removed app. shellcheck reports nothing new and i18n checks pass. Both this PR and the HTTPCache one must land before the v1.7.0 promote run. They merge cleanly in any order, #728 can go after the 1.7 snapshot.
2 parents 503275e + 5c5e250 commit 1fa33a6

8 files changed

Lines changed: 53 additions & 5 deletions

File tree

‎Makefile‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,13 +72,16 @@ else
7272
endif
7373

7474
# App lists (override on the command line: `make update-apps APPS="tenant redis"`)
75-
APPS ?= tenant clickhouse foundationdb harbor redis mongodb openbao rabbitmq postgres nats kafka mariadb qdrant
75+
APPS ?= tenant clickhouse foundationdb harbor redis mongodb openbao rabbitmq postgres nats kafka mariadb qdrant valkey opensearch bucket
7676
K8S ?= kubernetes
77+
K8S_NODES ?= kubernetes-nodes
7778
VMS ?= vm-disk vm-instance
7879
NETWORKING ?= vpc vpn http-cache tcp-balancer
7980
SERVICES ?= bootbox etcd ingress monitoring seaweedfs
81+
SERVICES += computeplane gateway
8082
APPS_DEST_DIR ?= content/en/docs/$(DOC_VERSION)/applications
8183
K8S_DEST_DIR ?= content/en/docs/$(DOC_VERSION)
84+
K8S_NODES_DEST_DIR ?= content/en/docs/$(DOC_VERSION)/kubernetes
8285
VMS_DEST_DIR ?= content/en/docs/$(DOC_VERSION)/virtualization
8386
NETWORKING_DEST_DIR ?= content/en/docs/$(DOC_VERSION)/networking
8487
SERVICES_DEST_DIR ?= content/en/docs/$(DOC_VERSION)/operations/services
@@ -99,6 +102,7 @@ update-networking:
99102

100103
update-k8s:
101104
./hack/update_apps.sh --index --apps "$(K8S)" --dest "$(K8S_DEST_DIR)" --branch "$(FETCH_REF)" --source-ref "$(SOURCE_REF)"
105+
./hack/update_apps.sh --apps "$(K8S_NODES)" --dest "$(K8S_NODES_DEST_DIR)" --branch "$(FETCH_REF)" --source-ref "$(SOURCE_REF)"
102106

103107
update-services:
104108
./hack/update_apps.sh --apps "$(SERVICES)" --dest "$(SERVICES_DEST_DIR)" --branch "$(FETCH_REF)" --source-ref "$(SOURCE_REF)" --pkgdir extra
@@ -186,6 +190,7 @@ template-networking:
186190
./hack/fill_templates.sh --apps "$(NETWORKING)" --dest "$(NETWORKING_DEST_DIR)" --branch "$(BRANCH)"
187191
template-k8s:
188192
./hack/fill_templates.sh --apps "$(K8S)" --dest "$(K8S_DEST_DIR)" --branch "$(BRANCH)"
193+
./hack/fill_templates.sh --apps "$(K8S_NODES)" --dest "$(K8S_NODES_DEST_DIR)" --branch "$(BRANCH)"
189194

190195
template-services:
191196
./hack/fill_templates.sh --apps "$(SERVICES)" --dest "$(SERVICES_DEST_DIR)" --branch "$(BRANCH)" --pkgdir extra
Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
title: "S3 Bucket Reference"
3+
linkTitle: "Bucket"
4+
weight: 50
5+
---
6+
Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
title: "Managed OpenSearch Service"
3+
linkTitle: "OpenSearch"
4+
weight: 50
5+
---
6+
Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
title: "Managed Valkey Service"
3+
linkTitle: "Valkey"
4+
weight: 50
5+
---
6+
Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
title: "Kubernetes Worker Node Pools"
3+
linkTitle: "Worker Node Pools"
4+
description: "Reference for KubernetesNodes, the resource that adds a pool of worker nodes to a managed Kubernetes cluster."
5+
weight: 10
6+
---
7+
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: "ComputePlane Service Reference"
3+
linkTitle: "ComputePlane"
4+
---
5+
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: "Tenant Gateway Reference"
3+
linkTitle: "Gateway"
4+
---
5+

‎hack/update_apps.sh‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,8 @@ Options:
1919
Notes:
2020
* Template markdown files are expected in DEST_DIR/_include (derived automatically).
2121
* Each template file should be named <app>.md.
22+
* An app without a template is skipped with a warning: the templates decide which apps
23+
that docs version covers.
2224
2325
Examples:
2426
hack/update_apps.sh --apps "tenant redis" --dest content/en/docs/reference/applications
@@ -84,7 +86,7 @@ RAW_BASE_URL="https://raw.githubusercontent.com/${SOURCE_REPO}/${BRANCH}/package
8486

8587

8688
# The per-app temp file is removed on every explicit exit path below; the trap
87-
# covers aborts between mktemp and those paths (set -e on touch/cp/heredoc).
89+
# covers aborts between mktemp and those paths (set -e on cp/heredoc).
8890
trap 'rm -f "${tmp:-}"' EXIT
8991

9092
for app in "${APPS[@]}"; do
@@ -101,6 +103,15 @@ for app in "${APPS[@]}"; do
101103
fi
102104
fi
103105

106+
# A patch release of an older line runs these same lists against a tree and a tag
107+
# that predate newer apps, whose README may 404 at that tag. Such a tree has no
108+
# template for them, so skip the app instead of fetching it or writing a page
109+
# without front matter.
110+
if [[ ! -f "$src_file" ]]; then
111+
echo "⚠️ Skipping $app: no template $src_file in this docs version" >&2
112+
continue
113+
fi
114+
104115
readme_url="${RAW_BASE_URL}/${app}/README.md"
105116
echo "Processing $app..."
106117

@@ -119,9 +130,6 @@ for app in "${APPS[@]}"; do
119130
exit 1
120131
fi
121132

122-
# Ensure template exists (touch if missing)
123-
[[ -f "$src_file" ]] || touch "$src_file"
124-
125133
# Copy template to destination (overwrite)
126134
cp "$src_file" "$dest_file"
127135

0 commit comments

Comments
 (0)