Skip to content

Commit 214e8bd

Browse files
raukadahopenshift-merge-bot[bot]
raukadah
authored and
openshift-merge-bot[bot]
committed
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 <raukadah@gmail.com>
1 parent 261e29f commit 214e8bd

File tree

8 files changed

+162
-0
lines changed

8 files changed

+162
-0
lines changed

‎.github/workflows/docs.yaml‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
name: Build Docs
2+
on:
3+
workflow_dispatch:
4+
push:
5+
branches:
6+
- main
7+
pull_request:
8+
branches:
9+
- main
10+
paths:
11+
- .github/workflows/docs*
12+
- docs/**
13+
- Gemfile
14+
jobs:
15+
deploy:
16+
if: github.repository == 'openstack-k8s-operators/watcher-operator'
17+
runs-on: ubuntu-latest
18+
steps:
19+
- name: Install Go
20+
uses: actions/setup-go@v3
21+
with:
22+
go-version: 1.21.x
23+
- uses: actions/checkout@v4
24+
with:
25+
# this fetches all branches. Needed because we need gh-pages branch for deploy to work
26+
fetch-depth: 0
27+
- uses: ruby/setup-ruby@v1.160.0
28+
with:
29+
ruby-version: '3.2'
30+
31+
- name: Build docs
32+
run: |
33+
make docs
34+
cp docs_build/watcher-operator/index.html index.html
35+
36+
- name: Prepare gh-pages branch
37+
run: |
38+
git config user.name github-actions
39+
git config user.email github-actions@github.com
40+
41+
git branch -D gh-pages &>/dev/null || true
42+
git checkout --orphan gh-pages
43+
git reset
44+
45+
- name: Commit asciidoc docs
46+
run: |
47+
git add index.html
48+
git commit -m "Rendered docs"
49+
50+
- name: Push rendered docs to gh-pages
51+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
52+
run: |
53+
git push --force origin gh-pages

‎.gitignore‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,13 @@
77
bin/*
88
Dockerfile.cross
99

10+
# Ruby bundle related files
11+
/.bundle
12+
/Gemfile.lock
13+
/local
14+
docs/main.adoc
15+
/docs_build
16+
1017
# Test binary, built with `go test -c`
1118
*.test
1219

‎.zuul.yaml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
github-check:
66
jobs:
77
- noop
8+
- watcher-operator-doc-preview
89
- openstack-meta-content-provider:
910
vars:
1011
cifmw_operator_build_meta_build: false
@@ -60,3 +61,13 @@
6061
source: "{{ watcher_hook }}"
6162
extra_vars:
6263
watcher_catalog_image: "{{ content_provider_registry_ip }}:5001/openstack-k8s-operators/watcher-operator-index:{{ zuul.patchset }}"
64+
65+
- job:
66+
name: watcher-operator-doc-preview
67+
parent: cifmw-doc
68+
files:
69+
- docs
70+
- Gemfile
71+
vars:
72+
asciidoc_available: true
73+
doc_available: false

‎Gemfile‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
source 'https://rubygems.org'
2+
3+
gem 'asciidoctor', '~> 2.0', '>= 2.0.20'
4+
5+
# Uncomment for ability to convert Markdown to AsciiDoc
6+
gem 'kramdown-asciidoc'
7+
8+
# Needed for https://github.com/ruby/rexml/issues/131#issuecomment-2116267578
9+
gem 'rexml', '= 3.2.6'

‎Makefile‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -452,3 +452,34 @@ run-with-webhook: export HEALTH_PORT?=33081
452452
run-with-webhook: manifests generate fmt vet ## Run a controller from your host.
453453
/bin/bash hack/clean_local_webhook.sh
454454
/bin/bash hack/run_with_local_webhook.sh
455+
456+
##@ Docs
457+
458+
.PHONY: docs-dependencies
459+
docs-dependencies: .bundle ## Convert markdown docs to ascii docs
460+
bundle exec kramdoc README.md -o docs/main.adoc
461+
462+
.PHONY: .bundle
463+
.bundle:
464+
if ! type bundle; then \
465+
echo "Bundler not found. On Linux run 'sudo dnf install /usr/bin/bundle' to install it."; \
466+
exit 1; \
467+
fi
468+
469+
bundle config set --local path 'local/bundle'; bundle install
470+
471+
.PHONY: docs
472+
docs: docs-dependencies ## Build docs
473+
cd docs; $(MAKE) html
474+
475+
.PHONY: docs-preview
476+
docs-preview: docs
477+
cd docs; $(MAKE) open-html
478+
479+
.PHONY: docs-watch
480+
docs-watch: docs-preview
481+
cd docs; $(MAKE) watch-html
482+
483+
.PHONY: docs-clean
484+
docs-clean:
485+
rm -r docs_build

‎docs/Makefile‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
BUILD_DIR = ../docs_build
2+
ROOTDIR = $(realpath .)
3+
NAME = watcher-operator
4+
DEST_DIR = $(BUILD_DIR)/$(NAME)
5+
DEST_HTML = $(DEST_DIR)/index.html
6+
IMAGES_DIR = $(DEST_DIR)/images
7+
IMAGES_TS = $(DEST_DIR)/.timestamp-images
8+
MAIN_SOURCE = main.adoc
9+
OTHER_SOURCES = $(shell find ./assemblies -type f)
10+
IMAGES = $(shell find ./images -type f)
11+
ALL_SOURCES = $(MAIN_SOURCE) $(OTHER_SOURCES) $(IMAGES)
12+
UNAME = $(shell uname)
13+
BUNDLE_EXEC ?= bundle exec
14+
15+
ifeq ($(UNAME), Linux)
16+
BROWSER_OPEN = xdg-open
17+
endif
18+
ifeq ($(UNAME), Darwin)
19+
BROWSER_OPEN = open
20+
endif
21+
22+
all: html
23+
24+
html: html-latest
25+
26+
html-latest: prepare $(IMAGES_TS) $(DEST_HTML)
27+
28+
prepare:
29+
@mkdir -p $(BUILD_DIR)
30+
@mkdir -p $(DEST_DIR) $(IMAGES_DIR)
31+
32+
clean:
33+
@rm -rf "$(DEST_DIR)"
34+
35+
watch-html:
36+
@which inotifywait > /dev/null || ( echo "ERROR: inotifywait not found, install inotify-tools" && exit 1 )
37+
while true; do \
38+
inotifywait -r -e modify -e create -e delete .; \
39+
sleep 0.5; \
40+
$(MAKE) html; \
41+
done
42+
43+
open-html: html
44+
${BROWSER_OPEN} "file://$(realpath $(ROOTDIR)/$(DEST_HTML))"
45+
46+
$(IMAGES_TS): $(IMAGES)
47+
cp $? $(IMAGES_DIR)
48+
touch $(IMAGES_TS)
49+
50+
$(DEST_HTML): $(ALL_SOURCES)
51+
$(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)

‎docs/assemblies/.gitkeep‎

Whitespace-only changes.

‎docs/images/.gitkeep‎

Whitespace-only changes.

0 commit comments

Comments
 (0)