diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml new file mode 100644 index 0000000..788903b --- /dev/null +++ b/.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/ diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..f07ba87 --- /dev/null +++ b/.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 diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..79e928f --- /dev/null +++ b/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) + diff --git a/README.md b/README.md new file mode 100644 index 0000000..fb43c12 --- /dev/null +++ b/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. diff --git a/antora-playbook.yml b/antora-playbook.yml new file mode 100644 index 0000000..b8a7b0a --- /dev/null +++ b/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 \ No newline at end of file diff --git a/antora.dockerfile b/antora.dockerfile new file mode 100644 index 0000000..a893d18 --- /dev/null +++ b/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 diff --git a/copy-rebuild-run.sh b/copy-rebuild-run.sh new file mode 100644 index 0000000..478cd62 --- /dev/null +++ b/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 diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..3debc76 --- /dev/null +++ b/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 + diff --git a/scripts/branchname.sh b/scripts/branchname.sh new file mode 100644 index 0000000..289d3c7 --- /dev/null +++ b/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} diff --git a/ui.dockerfile b/ui.dockerfile new file mode 100644 index 0000000..c193924 --- /dev/null +++ b/ui.dockerfile @@ -0,0 +1,2 @@ +FROM node:12-buster +WORKDIR /srv/docs-ui