Merge pull request #5389 from josegomezr/simplify_doc_build

Simplify generation of documentation

.github/checklist.yml

@@ -4,6 +4,6 @@ paths:
   "assets/stylesheets/**":
     - Consider providing screenshots in a PR comment to show the difference visually
   "docs/*.asciidoc":
-    - Consider generating documentation locally to verify it is rendered correctly using `tools/generate-htmldoc`
+    - Consider generating documentation locally to verify it is rendered correctly using `tools/generate-docs`
   "external/**":
     - Consider doing this change in the upstream repository directly, see external/os-autoinst-common/README.md

.gitignore

@@ -46,3 +46,5 @@ node_modules
 package-lock.json
 .tidyall.d/
 openqa-documentation.html
+docs/build/
+docs/vendor/

Makefile

@@ -350,3 +350,11 @@ test-helm-install:
 .PHONY: update-deps
 update-deps:
 	tools/update-deps --specfile dist/rpm/openQA.spec
+
+.PHONY: generate-docs
+generate-docs:
+	tools/generate-docs
+
+.PHONY: serve-docs
+serve-docs: generate-docs
+	(cd docs/build/; python3 -m http.server)

docs/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+gem 'asciidoctor'
+gem 'pygments.rb'

docs/Gemfile.lock

@@ -0,0 +1,15 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    asciidoctor (2.0.20)
+    pygments.rb (2.4.1)
+
+PLATFORMS
+  x86_64-linux
+
+DEPENDENCIES
+  asciidoctor
+  pygments.rb
+
+BUNDLED WITH
+   2.4.10

tools/generate-docs

@@ -0,0 +1,23 @@
+#!/bin/bash -e
+
+# Navigate to the docs directory
+cd "$(dirname "${BASH_SOURCE[0]}")/../docs"
+mkdir -p ./build/
+
+if [[ ! -e ./build/images ]]; then
+    ln -s ../images build/images
+fi
+
+asciidoctor_bin=$(command -v asciidoctor) || true
+
+if [[ -z "$asciidoctor_bin" ]]; then
+    echo "asciidoc not found in PATH."
+    echo "Fallback to Rubygem's Asciidoc"
+    export BUNDLE_PATH=./vendor/
+    # Make sure dependencies exist
+    bundle install
+    asciidoctor_bin="bundle exec asciidoctor"
+fi
+
+# Run asciidoc
+$asciidoctor_bin -o build/index.html ./index.asciidoc -d book