Add standalone documentation module with Antora

.github/workflows/docs.yml

@@ -0,0 +1,82 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - master
+    tags:
+      - "*"
+
+jobs:
+  antora:
+    runs-on: ubuntu-latest
+    if: ${{ contains(github.ref, 'tags') }}
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
+    - name: Configure Git
+      run: |
+        git config user.name "Antora via GitHub Actions"
+        git config user.email "actions@github.com"
+
+    - name: Parse semver string
+      id: semver
+      uses: booxmedialtd/ws-action-parse-semver@v1
+      with:
+        input_string: ${{ github.ref }}
+        version_extractor_regex: '\/v(.*)$'
+    - name: Set variables
+      run: |
+        echo "MINOR_VERSION=${{ steps.semver.outputs.major }}.${{ steps.semver.outputs.minor }}" >> $GITHUB_ENV
+        echo "BRANCH_NAME=docs/v${{ steps.semver.outputs.major }}.${{ steps.semver.outputs.minor }}" >> $GITHUB_ENV
+    - name: Set branch name for Prerelease
+      if: ${{ steps.semver.outputs.prerelease != '' }}
+      run: echo "BRANCH_NAME=${{ env.BRANCH_NAME }}-rc" >> $GITHUB_ENV
+
+    - name: Checkout remote branch if exists
+      run: git checkout ${{ env.BRANCH_NAME }}
+      continue-on-error: true
+    - name: Rebase if possible
+      run: git rebase ${GITHUB_REF##*/} ${{ env.BRANCH_NAME }}
+      continue-on-error: true
+    - name: Create new branch if not existing
+      run: git switch --create ${{ env.BRANCH_NAME }}
+      continue-on-error: true
+
+    - name: Patch Antora file for Release
+      run: yq eval 'del(.prerelease) | del (.display_version) | .version = "${{ env.MINOR_VERSION }}"' -i docs/antora.yml
+      if: ${{ steps.semver.outputs.prerelease == '' }}
+    - name: Patch Antora file for Prerelease
+      run: yq eval 'del (.display_version) | .version = "${{ env.MINOR_VERSION }}", .prerelease = "-${{ steps.semver.outputs.prerelease }}"' -i docs/antora.yml
+      if: ${{ steps.semver.outputs.prerelease != '' }}
+
+    - name: Commit
+      run: git commit --all --message "Update version for Antora"
+      continue-on-error: true
+    - name: Push
+      run: git push --atomic --force --set-upstream origin ${{ env.BRANCH_NAME }}
+
+    - name: Cleanup prerelease branch if existing
+      if: ${{ steps.semver.outputs.prerelease == '' }}
+      run: git push origin --delete ${{ env.BRANCH_NAME }}-rc
+      continue-on-error: true
+
+  gh-pages:
+    runs-on: ubuntu-latest
+    # The needs+if combo will cause this job to wait until Antora versioning is done for tags, but still run on master branch
+    needs: antora
+    if: always()
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
+
+    - name: Configure Git
+      run: |
+        git remote set-url origin "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}"
+        git config user.name "Antora via GitHub Actions"
+        git config user.email "actions@github.com"
+
+    - name: Publish documentation
+      run: make docs-publish

.gitignore

@@ -6,3 +6,8 @@ dist/
 # TODO: Adjust binary file name
 go-bootstrap
 *.out
+
+# Docs
+.cache/
+.public/
+node_modules/

Makefile

@@ -8,8 +8,12 @@ MAKEFLAGS += --no-builtin-variables
 .SECONDARY:
 .DEFAULT_GOAL := help
 
+# General variables
 include Makefile.vars.mk
 
+# Documentation module. If files not found, no warning/error is printed
+-include docs/antora-preview.mk docs/antora-build.mk
+
 .PHONY: help
 help: ## Show this help
 	@grep -E -h '\s##\s' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
@@ -24,7 +28,7 @@ build-bin: fmt vet ## Build binary
 
 .PHONY: build-docker
 build-docker: build-bin ## Build docker image
-	docker build -t $(CONTAINER_IMG) .
+	$(DOCKER_CMD) build -t $(CONTAINER_IMG) .
 
 .PHONY: test
 test: test-go ## All-in-one test
@@ -49,3 +53,7 @@ lint: fmt vet generate ## All-in-one linting
 .PHONY: generate
 generate: ## Generate additional code and artifacts
 	@go generate ./...
+
+.PHONY: clean
+clean: ## Cleans local build artifacts
+	rm -rf node_modules $(docs_out_dir) dist .cache

Makefile.vars.mk

@@ -9,7 +9,7 @@ PROJECT_OWNER ?= vshn
 BIN_FILENAME ?= $(PROJECT_NAME)
 
 ## Variables relevant for building with Docker
-
+DOCKER_CMD ?= docker
 IMG_TAG ?= latest
 # Image URL to use all building/pushing image targets
 CONTAINER_IMG ?= local.dev/$(PROJECT_OWNER)/$(PROJECT_NAME):$(IMG_TAG)

README.md

@@ -18,6 +18,11 @@ Template repository for common Go setups
   - Docker build for `latest` and `vx.y.z` tags
   - Push Docker image to GitHub's registry `ghcr.io`
 
+* Antora documentation
+  - Build default documentation with VSHN styling
+  - Publish to GitHub Pages by default (opt-out)
+  - Automated with GitHub workflows to build in `master` branch and (pre-)releases.
+
 ## TODO's after generating from this template
 
 TIP: You can search for these tasks using `grep -n -r "TODO:" .`
@@ -29,7 +34,10 @@ TIP: You can search for these tasks using `grep -n -r "TODO:" .`
 1. `Makefile.vars.mk`: Adjust project meta.
 1. `.github/ISSUE_TEMPLATE/config.yml` (optional): Enable forwarding questions to GitHub Discussions or other page.
 1. `.github/workflows/test.yml`: Update CodeClimate reporter ID (to be found in codeclimate.com Test coverage settings)
-
+1. `docs/antora.yml`: Adjust project meta.
+1. `docs/antora-playbook.yml`: Adjust project meta.
+1. `docs/modules/pages/index.adoc`: Edit start page.
+1. `docs/modules/nav.adoc`: Edit navigation.
 After completing a task, you can remove the comment in the files.
 
 ## Other repository settings
@@ -40,8 +48,40 @@ After completing a task, you can remove the comment in the files.
    - "Options > Automatically delete head branches" (enable)
    - "Branches > Default branch" (change to `master`) (VSHN's default)
    - "Branches > Branch protection rules":
-   - Branch name pattern: `master`
-   - Require status check to pass before merging: `["lint"]` (you may need to push come commits first)
+     - Branch name pattern: `master`
+     - Require status check to pass before merging: `["lint"]` (you may need to push come commits first)
+   -
 1. CodeClimate Settings
    - "Repo Settings > GitHub > Pull request status updates" (install)
    - "Repo Settings > Test coverage > Enforce {Diff,Total} Coverage" (configure to your liking)
+
+## Antora documentation
+
+This template comes with an Antora documentation module to help you create Asciidoctor documentation.
+By default, it is automatically published to GitHub Pages in `gh-pages` branch, however it can also be included in external Antora playbooks.
+
+### Setup GitHub Pages
+
+Let's prepare and empty `gh-pages` branch, but make sure to **commit or stash current changes first!**
+
+```bash
+current_branch=$(git rev-parse --abbrev-ref HEAD)
+initial_commit=$(git rev-list --max-parents=0 HEAD)
+git switch --create gh-pages $initial_commit
+git rm -r --cached .
+git commit -m "Prepare gh-pages branch"
+git push --set-upstream origin gh-pages
+git switch -f $current_branch
+```
+
+And you're done!
+GitHub automatically recognizes and sets up Pages if there's a `gh-pages` branch.
+
+---
+
+If you want to skip deployment to GitHub Pages you need to delete specific files and references:
+`rm -f .github/workflows/docs.yml docs/package*.json docs/antora-playbook.yml docs/antora-build.mk`
+
+---
+
+If you want to remove documentation completely simply run `rm -rf docs .github/workflows/docs.yml`

docs/antora-build.mk

@@ -0,0 +1,24 @@
+docs_out_dir := ./.public
+
+docker_opts ?= --rm --tty --user "$$(id -u)"
+
+antora_build_version ?= 2.3.3
+antora_cmd ?= $(DOCKER_CMD) run $(docker_opts) --volume "$${PWD}":/antora docker.io/vshn/antora:$(antora_build_version)
+antora_opts ?= --cache-dir=.cache/antora
+
+.PHONY: docs
+docs: docs-html ## All-in-one docs build
+
+.PHONY: docs-html
+docs-html: $(docs_out_dir)/index.html ## Generate HTML version of documentation with Antora, output at ./.public
+	@touch $(docs_out_dir)/.nojekyll
+
+$(docs_out_dir)/index.html:
+	$(antora_cmd) $(antora_opts) docs/antora-playbook.yml
+
+.PHONY: docs-publish
+docs-publish: node_modles docs-html ## Publishes the Antora documentation on Github Pages
+	npm run deploy
+
+node_modules:
+	npm install

docs/antora-playbook.yml

@@ -0,0 +1,19 @@
+site:
+  # TODO: Adjust project meta
+  title: Go Bootstrap
+  start_page: go-bootstrap::index.adoc
+  url: https://vshn.github.io/go-bootstrap
+content:
+  sources:
+    - url: ../antora
+      branches:
+        - HEAD
+        - docs/v*
+      start_path: docs
+ui:
+  bundle:
+    url: https://github.com/vshn/antora-ui-default/releases/download/2.0.15/ui-bundle.zip
+    snapshot: true
+output:
+  dir: .public/
+  clean: true

docs/antora-preview.mk

@@ -0,0 +1,7 @@
+
+antora_preview_version ?= 2.3.14
+antora_preview_cmd ?= $(DOCKER_CMD) run --rm --publish 2020:2020 --volume "${PWD}":/preview/antora docker.io/vshn/antora-preview:$(antora_preview_version) --style=vshn
+
+.PHONY: docs-preview
+docs-preview: ## Preview the documentation
+	$(antora_preview_cmd)

docs/antora.yml

@@ -0,0 +1,7 @@
+# TODO: Adjust project meta
+name: go-bootstrap
+title: Go Bootstrap
+version: master
+start_page: ROOT:index.adoc
+nav:
+  - modules/ROOT/nav.adoc

docs/modules/ROOT/nav.adoc

@@ -0,0 +1,15 @@
+// TODO: Edit navigation
+* xref:index.adoc[Introduction]
+* https://github.com/vshn/go-bootstrap/releases[Changelog,window=_blank]
+
+.Tutorials
+//* xref:tutorials/example.adoc[Example Tutorial]
+
+.How To
+//* xref:how-tos/example.adoc[Example How-To]
+
+.Technical reference
+//* xref:references/example.adoc[Example Reference]
+
+//.Explanation
+//* xref:explanations/example.adoc[Example Explanation]

docs/modules/ROOT/pages/index.adoc

@@ -0,0 +1,21 @@
+// TODO: Edit start page
+
+= {page-component-name}
+
+[discrete]
+== Introduction
+
+Go Bootstrap is a template repository that helps bootstrapping new Go applications quickly with a standardized setup.
+
+[discrete]
+== Documentation
+
+The documentation is inspired by the https://documentation.divio.com/[Divio's documentation structure]:
+
+Tutorials:: _Learning-oriented_: Simple lessons to learn about this project.
+
+How-to guides:: _Problem-oriented_: step-by-step guides to achieve a goal.
+
+Technical reference:: _Information-oriented_: explaining the inner ongoings.
+
+Explanation:: _Understanding-oriented_: puts this project in context.