Q: Initial Commit

.github/workflows/build.yml

@@ -0,0 +1,48 @@
+name: Build
+
+on:
+  push:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+        with:
+          token: ${{ secrets.BOT_PAT }}
+          submodules: recursive
+      - name: Checkout Submodules
+        id: checkout-submodules
+        run: |
+          pwd
+          ls -al
+          git submodule sync && git submodule update --init --recursive
+          ls -al
+      - name: Get Branch Name
+        shell: bash
+        run: echo "::set-output name=name::$(bash scripts/branchname.sh)"
+        id: branch
+      - name: Build UI
+        id: ui-build
+        run: make ui.build
+      - name: Build Antora
+        id: antora-build
+        run: |
+          pwd
+          ls -al
+          make antora.build
+      # - name: Deploy to Github Pages
+      #   id: deploy-gh
+      #   if: success() && steps.branch.outputs.name == 'master'
+      #   uses: crazy-max/ghaction-github-pages@v2
+      #   with:
+      #     target_branch: gh-pages
+      #     build_dir: build/site
+      #   env:
+      #     GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Generate Site Package
+        uses: actions/upload-artifact@v1
+        with:
+          name: Site
+          path: build/site/

.gitmodules

@@ -0,0 +1,6 @@
+[submodule "ui-customizations"]
+	path = ui-customizations
+	url = https://github.com/HMKnapp/qenta-docs-ui-customizations
+[submodule "content"]
+	path = content
+	url = https://github.com/HMKnapp/qenta-docs-content

Makefile

@@ -0,0 +1,47 @@
+# help: @ Lists available make tasks
+help:
+	@egrep -oh '[0-9a-zA-Z_\.\-]+:.*?@ .*' $(MAKEFILE_LIST) | \
+	awk 'BEGIN {FS = ":.*?@ "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}' | sort
+
+# antora.build: @ Builds documentation production output (to build/site)
+antora.build:
+	docker-compose run -u $$(id -u) antora antora --generator antora-site-generator-lunr --clean antora-playbook.yml
+#	docker-compose run -u $$(id -u) antora antora generate --clean antora-playbook.yml
+
+
+# antora.run: @ Serves documentation output (on port 8051)
+antora.run:
+	docker-compose run --service-ports antora http-server build/site -c-1
+
+# antora.watch: @ Watches for documentation changes and rebuilds (to build/site)
+antora.watch:
+	docker-compose run -u $$(id -u) -T antora onchange \
+	-i antora-playbook.yml 'components/**' 'docs/**' \
+	-- antora generate antora-playbook.yml
+
+# antora.shell: @ Opens bash shell in antora container
+antora.shell: CMD ?= /bin/sh
+antora.shell:
+	docker-compose run -u $$(id -u) antora $(CMD)
+
+# node_modules: @ Runs initial ui npm install
+node_modules:
+	docker-compose run ui npm install
+
+# ui.build: @ Builds ui production output (to build/ui-bundle.zip)
+ui.build: node_modules
+	docker-compose run -u $$(id -u) ui node_modules/.bin/gulp bundle
+
+# ui.lint: @ Runs ui linting
+ui.lint: node_modules
+	docker-compose run -u $$(id -u) ui node_modules/.bin/gulp lint
+
+# ui.run: @ Runs ui server in preview mode (on port 8052)
+ui.run: node_modules
+	docker-compose run -u $$(id -u) --service-ports ui node_modules/.bin/gulp preview
+
+# ui.shell: @ Opens bash shell in ui container
+ui.shell: CMD ?= /bin/bash
+ui.shell:
+	docker-compose run -u $$(id -u) ui $(CMD)
+

README.md

@@ -0,0 +1,80 @@
+# QENTA Online Guides
+
+## Overall Structure
+
+Organized as Git Submodules
+
+UI Customizations, Layout, Styles, frontend JS, search: `ui-customizations/`
+Content, pages, navigation, antora.yml: `content/`
+
+# Recommended Workflow
+
+## 1. Clone Recursively
+
+## 2. Make Changes
+
+After changing content, UI or any other part inside the submodules directories, **push the changes to the submodule(s) first**.
+
+Then push current repo to trigger a build.
+
+Pushes to `master` branch will be deployed **publically** to `gh-pages`
+Pushes to any other branch will be deployed to S3/branches/branch_name/
+
+# Build and Dev Locally
+
+Highly recommended to use the Dockerfiles (ui and antora) via the Makefile for each step.
+
+## 1. Build the UI
+```sh
+make ui.build
+```
+
+This creates `build/ui-bundle.zip` containing the UI, see it referenced in `antora-playbook.yml`
+Pay attention to output, linter is very strict and will not build the UI if you're sloppy.
+
+## 2. Build the Documentation
+```sh
+make antora.build
+```
+Creates the web pages in `build/site/`
+
+## 3. Start Local Webserver
+Contained in `antora.dockerfile`
+
+```sh
+make antora.run
+```
+
+NOTE: Console output says port `8080` but this is inside Docker, the forwarded port on `localhost` is `8051`, see `docker-compose.yml`
+
+[http://localhost:8051/](http://localhost:8051/)
+
+---
+
+# Important Files
+
+## Global Control
+`antora-playbook.yml`
+Disable displaying a _Page Edit_ button
+`url` can be a repository url or local folder. In our case it is both: a Git submodule
+
+```yaml
+content:
+  edit_url: ~
+  sources:
+  - url: ./
+    branches: HEAD
+    start_paths:
+    - content/*
+```
+
+## Content Control
+`antora.yml`
+
+### Page Navigation
+Navigation on the left of the page is controlled by `content/online-guides/modules/ROOT/nav.adoc`
+It is a simple list of pages and their hierarchy.
+
+# Dockerfiles
+To add search functionality `antora-site-generator-lunr` is installed in the container. 
+See `antora.dockerfile` for required ENV variables if you run antora without the provided Dockerfile/Makefile commands.

antora-playbook.yml

@@ -0,0 +1,20 @@
+site:
+  robots: allow
+  start_page: online-guides::start.adoc
+  title: QENTA Online Guides
+  url: https://guides.qenta.com
+content:
+  edit_url: ~
+  sources:
+  - url: ./
+    branches: HEAD
+    start_paths:
+    - content/*
+runtime:
+  cache_dir: ./build/cache
+ui:
+  bundle:
+    url: ./build/ui-bundle.zip
+  supplemental_files: ./ui-customizations/supplemental_ui
+urls:
+  html_extension_style: indexify

antora.dockerfile

@@ -0,0 +1,8 @@
+FROM antora/antora:2.3.4
+ENV DOCSEARCH_ENABLED=true
+ENV DOCSEARCH_ENGINE=lunr
+ENV NODE_PATH="/usr/local/lib/node_modules"
+ENV DOCSEARCH_INDEX_VERSION=latest
+RUN yarn global add http-server onchange
+RUN yarn global add antora-site-generator-lunr
+WORKDIR /srv/docs

copy-rebuild-run.sh

@@ -0,0 +1,14 @@
+make ui.build
+#rm -r content/online-guides/modules/ROOT/pages/* content/online-guides/modules/ROOT/assets
+#cp $HOME/Work/git/og2asciidoc/pages/start.adoc content/online-guides/modules/ROOT/pages/index.adoc
+#cp -r $HOME/Work/git/og2asciidoc/pages/* content/online-guides/modules/ROOT/pages/
+#mkdir -p content/online-guides/modules/ROOT/assets/
+#cp -r $HOME/Work/git/og2asciidoc/{images,attachments} content/online-guides/modules/ROOT/assets/
+
+# mkdir -p content/online-guides/modules/ROOT/assets/attachments/
+# mkdir -p content/online-guides/modules/ROOT/assets/images/
+
+# cp -r $HOME/Work/git/og2asciidoc/
+# cp -r $HOME/Work/git/og2asciidoc/pages/*
+make antora.build
+make antora.run

docker-compose.yml

@@ -0,0 +1,24 @@
+version: '3'
+
+services:
+
+  antora:
+    build:
+      context: .
+      dockerfile: antora.dockerfile
+    environment:
+      CI: 'true'
+    ports:
+    - 8051:8080
+    volumes:
+    - .:/srv/docs
+
+  ui:
+    build:
+      context: .
+      dockerfile: ui.dockerfile
+    ports:
+    - 8052:5252
+    volumes:
+    - .:/srv/docs-ui
+

scripts/branchname.sh

@@ -0,0 +1,24 @@
+#!/bin/bash
+
+# Extracts the branch name from Github CI Environment
+# On Push: returns branch name
+# On PR: returns "pr" and appends PR number
+
+if [[ ${GITHUB_EVENT_NAME} == "push" ]]; then
+  BUILD_NAME="${GITHUB_REF#refs/heads/}"
+else
+  PR="$(echo ${GITHUB_REF} | cut -d'/' -f3)"
+  BUILD_NAME="pr${PR}"
+fi
+
+if [[ ${GITHUB_REF} == "refs/tags/"* ]]; then
+  BUILD_NAME=$(sed 's|refs/tags/\(.\+\)|\1|' <<< ${GITHUB_REF})
+fi
+
+if [[ ! ${BUILD_NAME} ]]; then
+ echo "Failed to get name of branch or pull request" >&2
+ echo "DEBUG: GITHUB_EVENT_NAME == ${GITHUB_EVENT_NAME}" >&2
+ echo "DEBUG: GITHUB_REF == ${GITHUB_REF}" >&2
+fi
+
+echo ${BUILD_NAME}

ui.dockerfile

@@ -0,0 +1,2 @@
+FROM node:12-buster
+WORKDIR /srv/docs-ui