This is an automated email from the ASF dual-hosted git repository.
villebro pushed a commit to branch main
in repository
https://gitbox.apache.org/repos/asf/superset-kubernetes-operator.git
The following commit(s) were added to refs/heads/main by this push:
new 6091157 docs: auto-generate make-commands tables from Makefile
annotations (#79)
6091157 is described below
commit 60911576ee837736d15770d151fc63f15a4c40b8
Author: Ville Brofeldt <[email protected]>
AuthorDate: Tue May 26 15:02:24 2026 -0700
docs: auto-generate make-commands tables from Makefile annotations (#79)
---
CONTRIBUTING.md | 6 ++-
Makefile | 6 ++-
README.md | 81 ++++++++++++++++++++++++----
docs/contributing/development-setup.md | 90 ++++++++++++++++++++++---------
scripts/render-make-commands.sh | 96 ++++++++++++++++++++++++++++++++++
5 files changed, 241 insertions(+), 38 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c5c0a15..237dd4a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -20,8 +20,10 @@ under the License.
# Contributing to the Apache Superset Kubernetes Operator
Thank you for your interest in contributing! Please see the
-[Developer Guide](docs/developer-guide.md) for instructions on setting up
-your development environment, running tests, and submitting changes.
+[Development Setup guide](docs/contributing/development-setup.md) and the
+[Development Guidelines](docs/contributing/development-guidelines.md) for
+instructions on setting up your development environment, running tests, and
+submitting changes.
## Code of Conduct
diff --git a/Makefile b/Makefile
index 7e17781..bb78fb0 100644
--- a/Makefile
+++ b/Makefile
@@ -132,6 +132,10 @@ docs-api: crd-ref-docs ## Generate API reference
documentation from Go types.
supported-versions: ## Regenerate the supported-Kubernetes-versions table in
README.md and docs.
./scripts/render-supported-versions.sh
+.PHONY: make-commands
+make-commands: ## Regenerate the make-commands tables in README.md and the
contributing docs.
+ ./scripts/render-make-commands.sh
+
.PHONY: sync-supported-versions
sync-supported-versions: ## Sync .github/supported-k8s.json with the pinned
kind release's node images.
./scripts/sync-supported-versions.sh --write
@@ -167,7 +171,7 @@ helm-lint: helm-sync-crds ## Lint the Helm chart (syncs
CRDs first).
##@ Development
.PHONY: codegen
-codegen: manifests generate helm-sync-crds docs-api supported-versions ##
Regenerate all generated artifacts (CRDs, DeepCopy, Helm CRDs, API docs,
supported-versions table).
+codegen: manifests generate helm-sync-crds docs-api supported-versions
make-commands ## Regenerate all generated artifacts (CRDs, DeepCopy, Helm CRDs,
API docs, supported-versions table, make-commands tables).
.PHONY: clean
clean: ## Remove build artifacts, downloaded tools, and test cache.
diff --git a/README.md b/README.md
index 350da4f..4f93cb1 100644
--- a/README.md
+++ b/README.md
@@ -77,17 +77,76 @@ spec:
## Development
-```sh
-make build # Build operator binary
-make test # Run unit/integration tests
-make lint # Run golangci-lint
-make helm-lint # Lint the Helm chart
-make docs-serve # Serve docs locally (http://localhost:8000)
-make manifests # Regenerate CRDs + RBAC from markers
-make generate # Regenerate DeepCopy methods
-```
-
-After editing type definitions in `api/v1alpha1/`, run `make manifests
generate` and commit the generated files alongside your changes.
+<!-- BEGIN MAKE-COMMANDS -->
+<!-- generated by `make codegen`; do not edit -->
+### License
+
+| Command | Description |
+|---|---|
+| `make check-license` | Check Apache license headers using Apache Rat. |
+
+### Documentation
+
+| Command | Description |
+|---|---|
+| `make docs-serve` | Serve documentation locally with live reload. |
+| `make docs-build` | Build documentation site. |
+| `make docs-api` | Generate API reference documentation from Go types. |
+| `make supported-versions` | Regenerate the supported-Kubernetes-versions
table in README.md and docs. |
+| `make make-commands` | Regenerate the make-commands tables in README.md and
the contributing docs. |
+| `make sync-supported-versions` | Sync .github/supported-k8s.json with the
pinned kind release's node images. |
+| `make verify-supported-versions` | Verify supported-k8s.json matches the
pinned kind release and docs are up to date. |
+
+### Helm
+
+| Command | Description |
+|---|---|
+| `make helm-sync-crds` | Sync generated CRDs into the Helm chart. |
+| `make helm` | Sync CRDs into Helm chart and package it. |
+| `make helm-lint` | Lint the Helm chart (syncs CRDs first). |
+
+### Development
+
+| Command | Description |
+|---|---|
+| `make codegen` | Regenerate all generated artifacts (CRDs, DeepCopy, Helm
CRDs, API docs, supported-versions table, make-commands tables). |
+| `make clean` | Remove build artifacts, downloaded tools, and test cache. |
+| `make manifests` | Generate ClusterRole and CustomResourceDefinition
objects. |
+| `make generate` | Generate code containing DeepCopy, DeepCopyInto, and
DeepCopyObject method implementations. |
+| `make fmt` | Run go fmt against code. |
+| `make vet` | Run go vet against code. |
+| `make test` | Run all tests (unit + integration + e2e). |
+| `make test-unit` | Run unit tests (no envtest or cluster required). |
+| `make test-integration` | Run integration tests (requires envtest). |
+| `make setup-test-e2e` | Set up a Kind cluster for e2e tests if it does not
exist |
+| `make test-e2e` | Run the e2e tests. Expected an isolated environment using
Kind. |
+| `make cleanup-test-e2e` | Tear down the Kind cluster used for e2e tests |
+| `make lint` | Run golangci-lint linter |
+| `make lint-fix` | Run golangci-lint linter and perform fixes |
+| `make lint-config` | Verify golangci-lint linter configuration |
+| `make hooks` | Configure git to use .githooks/ for pre-commit hooks |
+
+### Build
+
+| Command | Description |
+|---|---|
+| `make build` | Build manager binary. |
+| `make run` | Run a controller from your host. |
+| `make docker-build` | Build docker image with the manager. |
+| `make docker-push` | Push docker image with the manager. |
+| `make build-installer` | Generate a consolidated YAML with CRDs and
deployment. |
+
+### Deployment
+
+| Command | Description |
+|---|---|
+| `make install` | Install CRDs into the K8s cluster specified in
~/.kube/config. |
+| `make uninstall` | Uninstall CRDs from the K8s cluster specified in
~/.kube/config. Call with ignore-not-found=true to ignore resource not found
errors during deletion. |
+| `make deploy` | Deploy controller to the K8s cluster specified in
~/.kube/config. |
+| `make undeploy` | Undeploy controller from the K8s cluster specified in
~/.kube/config. Call with ignore-not-found=true to ignore resource not found
errors during deletion. |
+<!-- END MAKE-COMMANDS -->
+
+After editing type definitions in `api/v1alpha1/`, run `make codegen` and
commit the generated files alongside your changes.
## License
diff --git a/docs/contributing/development-setup.md
b/docs/contributing/development-setup.md
index 396f3a3..b3bff19 100644
--- a/docs/contributing/development-setup.md
+++ b/docs/contributing/development-setup.md
@@ -129,32 +129,74 @@ kind delete cluster --name superset
## Make Commands
+<!-- BEGIN MAKE-COMMANDS -->
+<!-- generated by `make codegen`; do not edit -->
+### License
+
+| Command | Description |
+|---|---|
+| `make check-license` | Check Apache license headers using Apache Rat. |
+
+### Documentation
+
+| Command | Description |
+|---|---|
+| `make docs-serve` | Serve documentation locally with live reload. |
+| `make docs-build` | Build documentation site. |
+| `make docs-api` | Generate API reference documentation from Go types. |
+| `make supported-versions` | Regenerate the supported-Kubernetes-versions
table in README.md and docs. |
+| `make make-commands` | Regenerate the make-commands tables in README.md and
the contributing docs. |
+| `make sync-supported-versions` | Sync .github/supported-k8s.json with the
pinned kind release's node images. |
+| `make verify-supported-versions` | Verify supported-k8s.json matches the
pinned kind release and docs are up to date. |
+
+### Helm
+
+| Command | Description |
+|---|---|
+| `make helm-sync-crds` | Sync generated CRDs into the Helm chart. |
+| `make helm` | Sync CRDs into Helm chart and package it. |
+| `make helm-lint` | Lint the Helm chart (syncs CRDs first). |
+
+### Development
+
+| Command | Description |
+|---|---|
+| `make codegen` | Regenerate all generated artifacts (CRDs, DeepCopy, Helm
CRDs, API docs, supported-versions table, make-commands tables). |
+| `make clean` | Remove build artifacts, downloaded tools, and test cache. |
+| `make manifests` | Generate ClusterRole and CustomResourceDefinition
objects. |
+| `make generate` | Generate code containing DeepCopy, DeepCopyInto, and
DeepCopyObject method implementations. |
+| `make fmt` | Run go fmt against code. |
+| `make vet` | Run go vet against code. |
+| `make test` | Run all tests (unit + integration + e2e). |
+| `make test-unit` | Run unit tests (no envtest or cluster required). |
+| `make test-integration` | Run integration tests (requires envtest). |
+| `make setup-test-e2e` | Set up a Kind cluster for e2e tests if it does not
exist |
+| `make test-e2e` | Run the e2e tests. Expected an isolated environment using
Kind. |
+| `make cleanup-test-e2e` | Tear down the Kind cluster used for e2e tests |
+| `make lint` | Run golangci-lint linter |
+| `make lint-fix` | Run golangci-lint linter and perform fixes |
+| `make lint-config` | Verify golangci-lint linter configuration |
+| `make hooks` | Configure git to use .githooks/ for pre-commit hooks |
+
+### Build
+
+| Command | Description |
+|---|---|
+| `make build` | Build manager binary. |
+| `make run` | Run a controller from your host. |
+| `make docker-build` | Build docker image with the manager. |
+| `make docker-push` | Push docker image with the manager. |
+| `make build-installer` | Generate a consolidated YAML with CRDs and
deployment. |
+
+### Deployment
+
| Command | Description |
|---|---|
-| `make run` | Run the operator locally (connects to cluster via kubeconfig) |
-| `make deploy IMG=<image>` | Deploy operator in-cluster (CRDs + RBAC +
Deployment — superset of `make install`) |
-| `make install` | Install CRDs only |
-| `make undeploy` | Remove the in-cluster operator deployment |
-| `make uninstall` | Remove CRDs only |
-| `make manifests` | Regenerate CRD YAML and RBAC from kubebuilder markers |
-| `make generate` | Regenerate DeepCopy methods |
-| `make codegen` | Regenerate all generated artifacts (CRDs, DeepCopy, Helm
CRDs, API docs) |
-| `make build` | Build the operator binary |
-| `make docker-build IMG=<image>` | Build container image for the local
platform |
-| `make docker-buildx IMG=<image>` | Build and push multi-platform image
(linux/arm64, linux/amd64) |
-| `make test` | Run all tests (unit + integration + e2e) |
-| `make test-unit` | Run unit tests (no envtest or cluster required) |
-| `make test-integration` | Run integration tests (requires envtest) |
-| `make test-e2e` | Run e2e tests (requires Kind cluster) |
-| `make lint` | Run golangci-lint |
-| `make hooks` | Configure git to use `.githooks/` for pre-commit hooks |
-| `make helm` | Sync CRDs into Helm chart and package it |
-| `make helm-lint` | Lint the Helm chart |
-| `make docs-serve` | Serve docs locally at http://localhost:8000 |
-| `make docs-build` | Build docs site (runs in CI with `--strict`) |
-| `make docs-api` | Regenerate API reference from Go types |
-| `make check-license` | Check Apache license headers (requires Java) |
-| `make clean` | Remove build artifacts, downloaded tools, and test cache |
+| `make install` | Install CRDs into the K8s cluster specified in
~/.kube/config. |
+| `make uninstall` | Uninstall CRDs from the K8s cluster specified in
~/.kube/config. Call with ignore-not-found=true to ignore resource not found
errors during deletion. |
+| `make deploy` | Deploy controller to the K8s cluster specified in
~/.kube/config. |
+| `make undeploy` | Undeploy controller from the K8s cluster specified in
~/.kube/config. Call with ignore-not-found=true to ignore resource not found
errors during deletion. |
+<!-- END MAKE-COMMANDS -->
---
diff --git a/scripts/render-make-commands.sh b/scripts/render-make-commands.sh
new file mode 100755
index 0000000..a13d36c
--- /dev/null
+++ b/scripts/render-make-commands.sh
@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You 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.
+#
+# Render the make-commands tables from the Makefile's `##@ Section` headers
+# and `target: ## description` annotations into README.md and the contributing
+# docs, between sentinel comments:
+#
+# <!-- BEGIN MAKE-COMMANDS -->
+# ... generated block ...
+# <!-- END MAKE-COMMANDS -->
+#
+# The "General" and "Dependencies" sections are skipped — they contain `help`
+# and tool-bootstrap targets that aren't user-facing. To surface a target in
+# the docs, place it in a section other than those two.
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+MAKEFILE="${REPO_ROOT}/Makefile"
+TARGETS=(
+ "${REPO_ROOT}/README.md"
+ "${REPO_ROOT}/docs/contributing/development-setup.md"
+)
+SKIP_SECTIONS_RE='^(General|Dependencies)$'
+
+table="$(awk -v skip_re="${SKIP_SECTIONS_RE}" '
+ /^##@/ {
+ section = substr($0, 5)
+ sub(/^[ \t]+/, "", section)
+ sub(/[ \t]+$/, "", section)
+ if (section ~ skip_re) {
+ skip = 1
+ } else {
+ skip = 0
+ if (printed_section) print ""
+ print "### " section
+ print ""
+ print "| Command | Description |"
+ print "|---|---|"
+ printed_section = 1
+ }
+ next
+ }
+ /^[a-zA-Z_0-9-]+:.*##/ {
+ if (skip) next
+ idx = index($0, "##")
+ target = substr($0, 1, idx - 1)
+ sub(/:.*$/, "", target)
+ sub(/[ \t]+$/, "", target)
+ desc = substr($0, idx + 2)
+ sub(/^[ \t]+/, "", desc)
+ sub(/[ \t]+$/, "", desc)
+ printf "| `make %s` | %s |\n", target, desc
+ }
+' "${MAKEFILE}")"
+
+block="$({
+ echo '<!-- BEGIN MAKE-COMMANDS -->'
+ echo '<!-- generated by `make codegen`; do not edit -->'
+ echo "${table}"
+ echo '<!-- END MAKE-COMMANDS -->'
+})"
+
+for file in "${TARGETS[@]}"; do
+ if ! grep -q '<!-- BEGIN MAKE-COMMANDS -->' "${file}"; then
+ echo "no sentinel block found in ${file}" >&2
+ exit 1
+ fi
+ tmp="$(mktemp)"
+ BLOCK="${block}" awk '
+ /<!-- BEGIN MAKE-COMMANDS -->/ {
+ print ENVIRON["BLOCK"]
+ skip = 1
+ next
+ }
+ /<!-- END MAKE-COMMANDS -->/ {
+ skip = 0
+ next
+ }
+ !skip { print }
+ ' "${file}" > "${tmp}"
+ mv "${tmp}" "${file}"
+done
