Build Antora UI bundle from submodule rather than pulling from Nexus (#158)

* Build Antora UI bundle locally rather than pulling from Nexus

* Explicitly force Antora to refetch in CI builds

Co-authored-by: Sönke Liebau <[email protected]>

Author: nightkr

.github/workflows/build.yml

@@ -9,9 +9,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2.4.0
+        with:
+          submodules: true
       - uses: actions/setup-node@v2
         with:
           node-version: '16'
           cache: 'npm'
-      - run: npm install
-      - run: npx antora --fetch local-antora-playbook.yml
+      - run: npm ci
+      - run: make ANTORAFLAGS=--fetch

.github/workflows/deploy.yml

@@ -13,12 +13,14 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2.4.0
+        with:
+          submodules: true
       - uses: actions/setup-node@v2
         with:
           node-version: '16'
           cache: 'npm'
-      - run: npm install
-      - run: npx antora --fetch local-antora-playbook.yml
+      - run: npm ci
+      - run: make ANTORAFLAGS=--fetch
       - name: Publish to GitHub Pages
         uses: peaceiris/actions-gh-pages@v3
         with:

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "ui"]
+	path = ui
+	url = https://github.com/stackabletech/documentation-ui.git

Makefile

@@ -0,0 +1,8 @@
+PLAYBOOK := local-antora-playbook.yml
+ANTORAFLAGS :=
+
+build:
+	node_modules/.bin/gulp --cwd ui bundle
+	node_modules/.bin/antora generate $(PLAYBOOK) $(ANTORAFLAGS)
+
+.PHONY: build

README.adoc

@@ -8,17 +8,22 @@ It uses https://antora.org[Antora].
 
 This repository hosts the Antora playbook file as well as some generic documentation modules.
 
-To build the site install Antora and run:
+To build the site, pull submodules, install dependencies and run `make`:
 
-    antora antora-playbook.yml
+[source,console]
+----
+$ git submodule update --init
+$ npm ci
+$ make
+----
 
-NOTE: Antora caches all resources it downloads in the user's cache directory (e.g. `~/.cache/antora` directory on Linux). It will _not_ automatically update those. Use the `--fetch` parameter to update all sources.
+NOTE: Antora caches all resources it downloads in the user's cache directory (e.g. `~/.cache/antora` directory on Linux). It will _not_ automatically update those. Use the `--fetch` flag (`make ANTORAFLAGS=--fetch`) to update all sources.
 
 == Development
 
 === Generating the documentation
 
-During development, it can be helpful to use a playbook `local-antora-playbook.yml` which uses content from the local directory instead of the remote git repository.
+During development, it can be helpful to use a playbook `local-antora-playbook.yml` which uses content from the local directory instead of the remote git repository. The playbook used by the `Makefile` can be overridden using the `PLAYBOOK` variable (run `make PLAYBOOK=my-local-playbook.yml`).
 
 [source,yaml]
 ----

antora-playbook.yml

@@ -52,8 +52,7 @@ content:
 
 ui:
   bundle:
-    url: https://repo.stackable.tech/repository/misc/antora-ui-bundle.zip
-    snapshot: true
+    url: ./ui/build/ui-bundle.zip
   supplemental_files: ./node_modules/@antora/lunr-extension/supplemental_ui
 
 antora:

gitpod-antora-playbook.yml

@@ -52,8 +52,7 @@ content:
 
 ui:
   bundle:
-    url: https://repo.stackable.tech/repository/misc/antora-ui-bundle.zip
-    snapshot: true
+    url: ./ui/build/ui-bundle.zip
   supplemental_files: ./node_modules/@antora/lunr-extension/supplemental_ui
 
 antora:

local-antora-playbook.yml

@@ -53,8 +53,7 @@ content:
 
 ui:
   bundle:
-    url: https://repo.stackable.tech/repository/misc/antora-ui-bundle.zip
-    snapshot: true
+    url: ./ui/build/ui-bundle.zip
   supplemental_files: ./node_modules/@antora/lunr-extension/supplemental_ui
 
 antora: