Add ctlplane docs

Signed-off-by: Fabricio Aguiar <[email protected]>

.github/workflows/docs.yaml

@@ -0,0 +1,57 @@
+name: Build Docs
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+    paths:
+      - .github/workflows/docs*
+      - apis/client/v1beta1/**
+      - apis/core/v1beta1/**
+      - docs/**
+      - Gemfile
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install Go
+        uses: actions/setup-go@v3
+        with:
+          go-version: 1.20.x
+      - uses: actions/checkout@v4
+        with:
+          # this fetches all branches. Needed because we need gh-pages branch for deploy to work
+          fetch-depth: 0
+      - uses: ruby/[email protected]
+        with:
+          ruby-version: '3.2'
+
+      - name: Install Asciidoc
+        run: make docs-dependencies
+      - name: Build docs
+        run: |
+          make docs
+
+      - name: Prepare gh-pages branch
+        run: |
+          git restore docs/assemblies/custom_resources.adoc
+          git config user.name github-actions
+          git config user.email [email protected]
+
+          git branch -D gh-pages &>/dev/null || true
+          git checkout -b gh-pages 4cd0193fc6c5bc7e76f3a0148d0447fb0d7fbe6a
+
+      - name: Commit asciidoc docs
+        run: |
+          mkdir user dev
+          mv docs_build/ctlplane/index-upstream.html index.html
+          git add index.html
+          git commit -m "Rendered docs"
+
+      - name: Push rendered docs to gh-pages
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: |
+          git push --force origin gh-pages

.gitignore

@@ -37,3 +37,9 @@ CI_TOOLS_REPO
 # generated workspace file
 go.work
 go.work.sum
+
+# docs
+.bundle/
+docs_build/
+Gemfile.lock
+local/

Gemfile

@@ -0,0 +1,9 @@
+source 'https://rubygems.org'
+
+gem 'asciidoctor', '~> 2.0', '>= 2.0.20'
+
+# Uncomment for ability to render pdf:
+# gem 'asciidoctor-pdf', '~> 2.0', '>= 2.0.20'
+
+# Uncomment for ability to convert Markdown to AsciiDoc
+gem 'kramdown-asciidoc'

Makefile

@@ -76,6 +76,36 @@ DOCKER_BUILD_ARGS ?=
 .PHONY: all
 all: build
 
+##@ Docs
+
+.PHONY: docs-dependencies
+docs-dependencies: .bundle
+
+.PHONY: .bundle
+.bundle:
+	if ! type bundle; then \
+		echo "Bundler not found. On Linux run 'sudo dnf install /usr/bin/bundle' to install it."; \
+		exit 1; \
+	fi
+
+	bundle config set --local path 'local/bundle'; bundle install
+
+.PHONY: docs
+docs: manifests docs-dependencies crd-to-markdown  ## Build docs
+	CRD_MARKDOWN=$(CRD_MARKDOWN) MAKE=$(MAKE) ./docs/build_docs.sh
+
+.PHONY: docs-preview
+docs-preview: docs
+	cd docs; $(MAKE) open-html
+
+.PHONY: docs-watch
+docs-watch: docs-preview
+	cd docs; $(MAKE) watch-html
+
+.PHONY: docs-clean
+docs-clean:
+	rm -r docs_build
+
 ##@ General
 
 # The help target prints out all targets with their descriptions organized
@@ -214,11 +244,13 @@ $(LOCALBIN):
 KUSTOMIZE ?= $(LOCALBIN)/kustomize
 CONTROLLER_GEN ?= $(LOCALBIN)/controller-gen
 ENVTEST ?= $(LOCALBIN)/setup-envtest
+CRD_MARKDOWN ?= $(LOCALBIN)/crd-to-markdown
 GINKGO ?= $(LOCALBIN)/ginkgo
 
 ## Tool Versions
 KUSTOMIZE_VERSION ?= v3.8.7
 CONTROLLER_TOOLS_VERSION ?= v0.11.1
+CRD_MARKDOWN_VERSION ?= v0.0.3
 
 KUSTOMIZE_INSTALL_SCRIPT ?= "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh"
 .PHONY: kustomize
@@ -236,6 +268,11 @@ $(CONTROLLER_GEN): $(LOCALBIN)
 	test -s $(LOCALBIN)/controller-gen && $(LOCALBIN)/controller-gen --version | grep -q $(CONTROLLER_TOOLS_VERSION) || \
 	GOBIN=$(LOCALBIN) go install sigs.k8s.io/controller-tools/cmd/controller-gen@$(CONTROLLER_TOOLS_VERSION)
 
+.PHONY: crd-to-markdown
+crd-to-markdown: $(CRD_MARKDOWN) ## Download crd-to-markdown locally if necessary.
+$(CRD_MARKDOWN): $(LOCALBIN)
+	test -s $(LOCALBIN)/crd-to-markdown || GOBIN=$(LOCALBIN) go install github.com/clamoriniere/crd-to-markdown@$(CRD_MARKDOWN_VERSION)
+
 .PHONY: envtest
 envtest: $(ENVTEST) ## Download envtest-setup locally if necessary.
 $(ENVTEST): $(LOCALBIN)

OWNERS_ALIASES

@@ -5,6 +5,8 @@ aliases:
   - lewisdenny
   - frenzyfriday
   - viroel
+  docs-approvers:
+  - igallagh-redhat
   openstack-approvers:
   - abays
   - dprince

docs/Makefile

@@ -0,0 +1,61 @@
+BUILD = upstream
+BUILD_DIR = ../docs_build
+ROOTDIR = $(realpath .)
+NAME = ctlplane
+DEST_DIR = $(BUILD_DIR)/$(NAME)
+DEST_HTML = $(DEST_DIR)/index-$(BUILD).html
+DEST_PDF = $(BUILD_DIR)/$(NAME)-$(BUILD).pdf
+IMAGES_DIR = $(DEST_DIR)/images
+IMAGES_TS = $(DEST_DIR)/.timestamp-images
+MAIN_SOURCE = user.adoc
+OTHER_SOURCES = $(shell find ./assemblies -type f)
+IMAGES = $(shell find ./images -type f)
+ALL_SOURCES = $(MAIN_SOURCE) $(OTHER_SOURCES) $(IMAGES)
+UNAME = $(shell uname)
+BUNDLE_EXEC ?= bundle exec
+
+ifeq ($(UNAME), Linux)
+BROWSER_OPEN = xdg-open
+endif
+ifeq ($(UNAME), Darwin)
+BROWSER_OPEN = open
+endif
+
+all: html
+
+html: html-latest
+
+html-latest: prepare $(IMAGES_TS) $(DEST_HTML)
+
+pdf: prepare $(DEST_PDF)
+
+prepare:
+	@mkdir -p $(BUILD_DIR)
+	@mkdir -p $(DEST_DIR) $(IMAGES_DIR)
+
+clean:
+	@rm -rf "$(DEST_DIR)" "$(DEST_PDF)"
+
+watch-html:
+	@which inotifywait > /dev/null || ( echo "ERROR: inotifywait not found, install inotify-tools" && exit 1 )
+	while true; do \
+		inotifywait -r -e modify -e create -e delete .; \
+		sleep 0.5; \
+		$(MAKE) html; \
+	done
+
+open-html: html
+	${BROWSER_OPEN} "file://$(realpath $(ROOTDIR)/$(DEST_HTML))"
+
+open-pdf: pdf
+	${BROWSER_OPEN} "$(realpath $(ROOTDIR)/$(DEST_PDF))"
+
+$(IMAGES_TS): $(IMAGES)
+	cp $? $(IMAGES_DIR)
+	touch $(IMAGES_TS)
+
+$(DEST_HTML): $(ALL_SOURCES)
+	$(BUNDLE_EXEC) asciidoctor -a source-highlighter=highlightjs -a highlightjs-languages="yaml,bash" -a highlightjs-theme="monokai" -a build=$(BUILD) -b xhtml5 -d book -o $@ $(MAIN_SOURCE)
+
+$(DEST_PDF): $(ALL_SOURCES)
+	$(BUNDLE_EXEC) asciidoctor-pdf -a build=$(BUILD) -d book -o $@ $(MAIN_SOURCE) $(IMAGES)

docs/OWNERS

@@ -0,0 +1,6 @@
+# See the OWNERS docs at https://go.k8s.io/owners
+approvers:
+  - docs-approvers
+
+reviewers:
+  - docs-approvers