feat(docs): prepare and publish v2 docs website

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

@@ -0,0 +1,89 @@
+name: Docs
+
+on:
+  workflow_dispatch:
+  pull_request:
+    branches:
+      - v2-next
+    paths:
+      - "docs/**"
+      - "cli/**"
+      - "cmd/**"
+      - "backend/**"
+      - "engine/**"
+      - "pkg/**"
+      - "deploy/charts/**"
+      - "sdk/apis/**"
+      - "go.mod"
+      - "go.sum"
+      - "sdk/go.mod"
+      - "sdk/go.sum"
+      - "Makefile"
+      - ".github/workflows/docs-gen-and-push.yaml"
+  push:
+    branches:
+      - v2-next
+      - docs-v2
+    paths:
+      - "docs/**"
+      - "cli/**"
+      - "cmd/**"
+      - "backend/**"
+      - "engine/**"
+      - "pkg/**"
+      - "deploy/charts/**"
+      - "sdk/apis/**"
+      - "go.mod"
+      - "go.sum"
+      - "sdk/go.mod"
+      - "sdk/go.sum"
+      - "Makefile"
+      - ".github/workflows/docs-gen-and-push.yaml"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
+        with:
+          go-version-file: go.mod
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: docs/requirements.txt
+      - run: make docs-venv build-docs
+
+  publish:
+    if: >-
+      github.repository == 'kbind-dev/kbind' &&
+      github.event_name != 'pull_request' &&
+      (github.ref == 'refs/heads/v2-next' || github.ref == 'refs/heads/docs-v2')
+    needs: build
+    permissions:
+      contents: write
+    concurrency:
+      group: Docs
+      cancel-in-progress: false
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
+        with:
+          go-version-file: go.mod
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: docs/requirements.txt
+      - name: Publish preview without changing latest
+        env:
+          PUSH: "1"
+        run: |
+          git config user.name "kbind-ci-bot"
+          git config user.email "no-reply@kbind.dev"
+          make docs-venv deploy-docs

Makefile

@@ -22,6 +22,8 @@ SETUP_ENVTEST  ?= go run sigs.k8s.io/controller-runtime/tools/setup-envtest@rele
 CHART ?= deploy/charts/konnector-v2
 BACKEND_CHART ?= deploy/charts/backend-v2
 IMAGE ?= ghcr.io/kbind-dev/konnector:dev
+DOCS_VENV ?= $(CURDIR)/docs/.venv
+CRD_REF_DOCS ?= go run github.com/elastic/crd-ref-docs@v0.3.0
 
 .PHONY: all
 all: codegen build
@@ -177,3 +179,36 @@ helm-push:
 	  echo "==> pushing $$chart-$(CHART_VERSION).tgz to oci://$(HELM_REPO)"; \
 	  $(HELM) push bin/charts/$$chart-$(CHART_VERSION).tgz oci://$(HELM_REPO) || exit 1; \
 	done
+
+.PHONY: docs-venv
+docs-venv:
+	python3 -m venv $(DOCS_VENV)
+	$(DOCS_VENV)/bin/python -m pip install --upgrade pip
+	$(DOCS_VENV)/bin/python -m pip install -r docs/requirements.txt
+
+.PHONY: generate-cli-docs
+generate-cli-docs:
+	mkdir -p docs/content/reference/cli
+	go run ./docs/generators/cli-doc > docs/content/reference/cli/index.md
+
+.PHONY: generate-api-docs
+generate-api-docs:
+	mkdir -p docs/content/reference/crd
+	$(CRD_REF_DOCS) --source-path=./sdk/apis \
+		--config=docs/generators/crd-ref/config.yaml --renderer=markdown \
+		--output-path=docs/content/reference/crd/index.md
+
+.PHONY: generate-docs
+generate-docs: generate-cli-docs generate-api-docs
+
+.PHONY: build-docs
+build-docs: generate-docs
+	cd docs && $(DOCS_VENV)/bin/mkdocs build --strict
+
+.PHONY: serve-docs
+serve-docs: generate-docs
+	cd docs && $(DOCS_VENV)/bin/mkdocs serve
+
+.PHONY: deploy-docs
+deploy-docs: build-docs
+	PATH="$(DOCS_VENV)/bin:$$PATH" bash docs/scripts/deploy-docs.sh

deploy/charts/backend-v2/files/crds/catalog.kbind.io_collections.yaml

@@ -27,7 +27,7 @@ spec:
     schema:
       openAPIV3Schema:
         description: |-
-          Collection groups Exports for UI/CLI browsing. Pure presentation; nothing
+          Collection groups Exports for UI/CLI browsing. Pure presentation, nothing
           binds to a Collection.
         properties:
           apiVersion:

deploy/charts/backend-v2/files/crds/catalog.kbind.io_exports.yaml

@@ -33,9 +33,9 @@ spec:
           Export is one curated offering in the provider's catalog: human-facing
           metadata plus defaults on top of one or more exported APIs. The catalog is
           derived-from-core-truth: an Export listing an API that is not actually
-          exported (label/boundary) gets a condition and is hidden by the gateway —
+          exported (label/boundary) gets a condition and is hidden by the gateway,
           the export label remains the source of truth, the catalog is presentation
-          and defaults. Lives on the provider; the konnector never sees it.
+          and defaults. Lives on the provider, the konnector never sees it.
         properties:
           apiVersion:
             description: |-
@@ -65,7 +65,7 @@ spec:
                   description: |-
                     APIRef identifies an exported API by its CRD name on the provider,
                     i.e. "<plural>.<group>" (for example "mangodbs.mangodb.io"). Under the
-                    OpenAPI schema source there is no CRD object behind the name; it is still
+                    OpenAPI schema source there is no CRD object behind the name, it is still
                     just resource + group.
                   properties:
                     name:

deploy/charts/backend-v2/files/crds/iam.kbind.io_grants.yaml

@@ -38,7 +38,7 @@ spec:
         description: |-
           Grant records that an identity was issued credentials for an export. The
           gateway creates it with the export's API list and defaults resolved in
-          (issuance is a stable record even if the catalog entry changes later); the
+          (issuance is a stable record even if the catalog entry changes later), the
           issuer controller provisions the tenancy boundary, ServiceAccount, RBAC and
           token from the spec and reports the artifacts in status. Deleting the Grant
           revokes: the issuer's cleanup finalizer unwinds everything it provisioned.
@@ -72,7 +72,7 @@ spec:
                   description: |-
                     APIRef identifies an exported API by its CRD name on the provider,
                     i.e. "<plural>.<group>" (for example "mangodbs.mangodb.io"). Under the
-                    OpenAPI schema source there is no CRD object behind the name; it is still
+                    OpenAPI schema source there is no CRD object behind the name, it is still
                     just resource + group.
                   properties:
                     name:

deploy/charts/backend-v2/templates/NOTES.txt

@@ -8,14 +8,14 @@ Reach the gateway (port-forward for a quick look):
 
   kubectl -n {{ .Release.Namespace }} port-forward svc/{{ include "backend.fullname" . }} 8080:{{ .Values.service.port }}
   open http://localhost:8080          # the catalog UI
-  kbind login http://localhost:8080   # CLI login
+  kubectl bind login http://localhost:8080   # CLI login
 
 {{- if not .Values.externalURL }}
-NOTE: externalURL is not set — OIDC callbacks and pickup URLs default to
+NOTE: externalURL is not set, OIDC callbacks and pickup URLs default to
 localhost. Set it (and expose the Service) for real consumers.
 {{- end }}
 {{- if not .Values.cookieKeys.existingSecret }}
-NOTE: cookieKeys.existingSecret is not set — sessions are ephemeral and will
+NOTE: cookieKeys.existingSecret is not set, sessions are ephemeral and will
 not survive restarts or work across replicas.
 {{- end }}
 {{- end }}

deploy/charts/konnector-v2/files/crds/core.kbind.io_bindings.yaml

@@ -65,7 +65,7 @@ spec:
                   description: |-
                     APIRef identifies an exported API by its CRD name on the provider,
                     i.e. "<plural>.<group>" (for example "mangodbs.mangodb.io"). Under the
-                    OpenAPI schema source there is no CRD object behind the name; it is still
+                    OpenAPI schema source there is no CRD object behind the name, it is still
                     just resource + group.
                   properties:
                     name:
@@ -81,7 +81,7 @@ spec:
                 default: Fail
                 description: |-
                   conflictPolicy controls what happens when a target object already exists.
-                  Fail (default) leaves a foreign object untouched and records a conflict;
+                  Fail (default) leaves a foreign object untouched and records a conflict,
                   Adopt takes ownership of an un-owned object. Adopt never steals an object
                   already carrying another binding's/consumer's markers.
                 enum:
@@ -103,7 +103,7 @@ spec:
               relatedResources:
                 description: |-
                   relatedResources are Secrets/ConfigMaps synced alongside instances of the
-                  bound APIs. Not yet synced in the alpha POC.
+                  bound APIs.
                 items:
                   description: |-
                     RelatedResource selects auxiliary objects (Secrets/ConfigMaps) to sync
@@ -210,7 +210,7 @@ spec:
                     conflictCount:
                       description: |-
                         conflictCount is the number of objects skipped due to foreign ownership.
-                        Per-object detail lives on each object's own condition, not here.
+                        Per-object details are recorded in consumer-object annotations and Events.
                       format: int32
                       type: integer
                     crdHash:

deploy/charts/konnector-v2/files/crds/core.kbind.io_clusterbindings.yaml

@@ -63,7 +63,7 @@ spec:
                   description: |-
                     APIRef identifies an exported API by its CRD name on the provider,
                     i.e. "<plural>.<group>" (for example "mangodbs.mangodb.io"). Under the
-                    OpenAPI schema source there is no CRD object behind the name; it is still
+                    OpenAPI schema source there is no CRD object behind the name, it is still
                     just resource + group.
                   properties:
                     name:
@@ -79,7 +79,7 @@ spec:
                 default: Fail
                 description: |-
                   conflictPolicy controls what happens when a target object already exists.
-                  Fail (default) leaves a foreign object untouched and records a conflict;
+                  Fail (default) leaves a foreign object untouched and records a conflict,
                   Adopt takes ownership of an un-owned object. Adopt never steals an object
                   already carrying another binding's/consumer's markers.
                 enum:
@@ -101,7 +101,7 @@ spec:
               relatedResources:
                 description: |-
                   relatedResources are Secrets/ConfigMaps synced alongside instances of the
-                  bound APIs. Not yet synced in the alpha POC.
+                  bound APIs.
                 items:
                   description: |-
                     RelatedResource selects auxiliary objects (Secrets/ConfigMaps) to sync
@@ -208,7 +208,7 @@ spec:
                     conflictCount:
                       description: |-
                         conflictCount is the number of objects skipped due to foreign ownership.
-                        Per-object detail lives on each object's own condition, not here.
+                        Per-object details are recorded in consumer-object annotations and Events.
                       format: int32
                       type: integer
                     crdHash:

deploy/charts/konnector-v2/files/crds/core.kbind.io_connections.yaml

@@ -73,8 +73,7 @@ spec:
                     minLength: 1
                     type: string
                   namespace:
-                    description: namespace of the Secret. Must be the konnector's
-                      designated namespace.
+                    description: namespace of the Secret.
                     minLength: 1
                     type: string
                 required:

docs/.gitignore

@@ -0,0 +1,3 @@
+/.venv/
+/generated/
+/.cache/

docs/README.md

@@ -0,0 +1,76 @@
+# Documentation and publishing
+
+The v2 site keeps the original MkDocs Material theme, **mike** versioning,
+and directory-based navigation using the **awesome-pages** plugin.
+Content lives under `docs/content`, each section's `.pages` file controls
+its navigation. Only this directory is published, design proposals and
+release-maintenance notes remain repository documents.
+
+## Build and preview
+
+Use Python with `venv` and the Go version from `go.mod`. CI uses Python
+3.12. From the repository root:
+
+```bash
+make docs-venv
+make build-docs
+make serve-docs
+```
+
+The first command installs dependencies into the ignored `docs/.venv`.
+`build-docs` generates references and runs a strict MkDocs build.
+`serve-docs` serves a local preview at `http://127.0.0.1:8000`, it does not
+modify any published version or redirect.
+
+The API generator scans this checkout's `sdk/apis` using a pinned
+`crd-ref-docs` version. The CLI generator uses this checkout's Cobra
+command tree. Generated references and the built site are ignored by git.
+After changing API types or CLI definitions, restart the preview or run
+`make generate-docs` again.
+
+## Non-default v2 publication
+
+The preview is always published as **`v2`**, displayed in the
+version selector as **v2 (preview)**:
+
+<https://docs.kbind.dev/v2/>
+
+Publication deliberately does **not** derive the version from the newest
+tag, assign the `latest` alias, call `mike set-default`, or replace the
+root redirect. The existing 0.x versions, `latest`, and custom domain
+stay in the `gh-pages` branch.
+
+The **Docs** workflow (`.github/workflows/docs-gen-and-push.yaml`)
+builds relevant pull requests without deployment. Pushes to `v2-next`
+or the temporary `docs-v2` preparation branch, and manual dispatches on
+those branches, can publish only in `kbind-dev/kbind` once the workflow
+is committed there. Forks build but
+cannot publish to the canonical site. Publication shares the `Docs`
+concurrency group with the stable docs workflow and never force-pushes.
+
+## Publish a checkout manually
+
+Use a clean checkout containing the intended documentation, review its
+build, and confirm the selected remote is the canonical repository. For
+example, if it is named `upstream`:
+
+```bash
+git remote get-url upstream
+make docs-venv
+REMOTE=upstream make deploy-docs
+git diff --stat upstream/gh-pages..gh-pages
+git diff upstream/gh-pages..gh-pages -- versions.json index.html CNAME latest
+git push upstream gh-pages:gh-pages
+```
+
+`deploy-docs` fetches the existing publishing branch and makes a local mike
+commit. **It does not push by default.** Review that only `v2/` and the
+new `versions.json` entry changed before pushing. If someone publishes in
+the meantime, fetch and rebuild on the updated branch rather than
+force-pushing.
+
+CI passes `PUSH=1` to publish immediately after the strict build.
+`REMOTE` defaults to `origin` and `BRANCH` to `gh-pages`, override them
+only deliberately. There is intentionally no `VERSION` or default-version
+switch in the preview publisher. Making v2 the stable default is a
+separate release decision.