Make targets and github workflow for publishing docs

This pr adds:
- Make docs to build the docs using ascii
  * Install ascii doc ruby packages using bundle
  * Convert README.md to main.adoc
  * Use Make target to build html files
- Github action to build and publish docs on github pages.
- Zuul job to preview docs

Signed-off-by: Chandan Kumar <[email protected]>

.github/workflows/docs.yaml

@@ -0,0 +1,53 @@
+name: Build Docs
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+    paths:
+      - .github/workflows/docs*
+      - docs/**
+      - Gemfile
+jobs:
+  deploy:
+    if: github.repository == 'openstack-k8s-operators/watcher-operator'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install Go
+        uses: actions/setup-go@v3
+        with:
+          go-version: 1.21.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: Build docs
+        run: |
+          make docs
+          cp docs_build/watcher-operator/index.html index.html
+
+      - name: Prepare gh-pages branch
+        run: |
+          git config user.name github-actions
+          git config user.email [email protected]
+
+          git branch -D gh-pages &>/dev/null || true
+          git checkout --orphan gh-pages
+          git reset
+
+      - name: Commit asciidoc docs
+        run: |
+          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

@@ -7,6 +7,13 @@
 bin/*
 Dockerfile.cross
 
+# Ruby bundle related files
+/.bundle
+/Gemfile.lock
+/local
+docs/main.adoc
+/docs_build
+
 # Test binary, built with `go test -c`
 *.test
 

.zuul.yaml

@@ -5,6 +5,7 @@
     github-check:
       jobs:
         - noop
+        - watcher-operator-doc-preview
         - openstack-meta-content-provider:
             vars:
               cifmw_operator_build_meta_build: false
@@ -60,3 +61,13 @@
           source: "{{ watcher_hook }}"
           extra_vars:
             watcher_catalog_image: "{{ content_provider_registry_ip }}:5001/openstack-k8s-operators/watcher-operator-index:{{ zuul.patchset }}"
+
+- job:
+    name: watcher-operator-doc-preview
+    parent: cifmw-doc
+    files:
+      - docs
+      - Gemfile
+    vars:
+      asciidoc_available: true
+      doc_available: false

Gemfile

@@ -0,0 +1,9 @@
+source 'https://rubygems.org'
+
+gem 'asciidoctor', '~> 2.0', '>= 2.0.20'
+
+# Uncomment for ability to convert Markdown to AsciiDoc
+gem 'kramdown-asciidoc'
+
+# Needed for https://github.com/ruby/rexml/issues/131#issuecomment-2116267578
+gem 'rexml', '= 3.2.6'

Makefile

@@ -452,3 +452,34 @@ run-with-webhook: export HEALTH_PORT?=33081
 run-with-webhook: manifests generate fmt vet ## Run a controller from your host.
 	/bin/bash hack/clean_local_webhook.sh
 	/bin/bash hack/run_with_local_webhook.sh
+
+##@ Docs
+
+.PHONY: docs-dependencies
+docs-dependencies: .bundle ## Convert markdown docs to ascii docs
+	bundle exec kramdoc README.md -o docs/main.adoc
+
+.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: docs-dependencies ## Build docs
+	cd docs; $(MAKE) html
+
+.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

docs/Makefile

@@ -0,0 +1,51 @@
+BUILD_DIR = ../docs_build
+ROOTDIR = $(realpath .)
+NAME = watcher-operator
+DEST_DIR = $(BUILD_DIR)/$(NAME)
+DEST_HTML = $(DEST_DIR)/index.html
+IMAGES_DIR = $(DEST_DIR)/images
+IMAGES_TS = $(DEST_DIR)/.timestamp-images
+MAIN_SOURCE = main.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)
+
+prepare:
+	@mkdir -p $(BUILD_DIR)
+	@mkdir -p $(DEST_DIR) $(IMAGES_DIR)
+
+clean:
+	@rm -rf "$(DEST_DIR)"
+
+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))"
+
+$(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" --failure-level WARN -a build=$(BUILD) -b xhtml5 -d book -o $@ $(MAIN_SOURCE)