Add a GHA workflow to deploy the site

Author: bbatsov

.github/workflows/publish.yml

@@ -0,0 +1,40 @@
+name: Publish to GitHub Pages
+on:
+  push:
+    branches: [master]
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+concurrency:
+  group: github-pages
+  cancel-in-progress: false
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+      - name: Install Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "18"
+      - name: Install Antora
+        run: npm i antora
+      - name: Generate Site
+        run: npx antora antora-playbook.yml
+      - name: Upload Artifacts
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: build/site
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

Makefile

@@ -7,8 +7,3 @@ npm: package.json
 
 build: npm
 	npm run antora -- --fetch antora-playbook.yml
-
-deploy: build
-	git add docs
-	git commit -m 'Update site docs'
-	git push

README.adoc

@@ -2,7 +2,7 @@
 
 The site is generated from the AsciiDoc files in the link:https://github.com/nrepl/nrepl/tree/master/doc[doc] folder of nREPL's GitHub repo and is published to https://nrepl.org.
 link:https://antora.org[Antora] is used to convert the manual into HTML.
-The filesystem layout is described at https://docs.antora.org/antora/2.0/component-structure/
+The filesystem layout is described at https://docs.antora.org/antora/3.1/component-structure/
 
 To make changes to the manual you simply have to change the files under `doc`.
 The manual will be regenerated manually periodically.
@@ -19,16 +19,44 @@ $ cd nrepl.org
 $ make build
 ----
 
-After you're done with the initial setup you can use `make` to push changes to the site:
+To check the generated site you can simply open `build/site/index.html` in your favourite browser.
+
+== Deploying the Site
+
+NOTE: You'll need commit access to the repository for this to work.
+
+The site is automatically deployed to GitHub pages using a GitHub Action.
+The action will be triggered by any push to the `master` branch.
+It can also be triggered manually if needed.
+
+== Using Docker
+
+If you prefer not to install Antora on your local machine, you can build the documentation
+inside a Docker container like this:
 
 [source]
 ----
-$ make deploy
+$ docker run --rm -t -v $(pwd):/build/site antora/antora:3.1.10 --fetch /docs/antora-playbook.yml
 ----
 
-NOTE: You'll need commit access to the repository for this to work.
+== Updating the Playbook
+
+When cutting new releases you'll have to updated `antora-playbook.yml` to mention
+their relevant tags from which the documentation needs to be build. Here's how this
+looks for one of the projects:
+
+[source]
+----
+- url: https://github.com/nrepl/nrepl.git
+  branches: master
+  tags: ['v1.7.0', 'v1.8.0']
+  start_path: docs
+----
+
+TIP: You need to add one such block for each new nREPL module you're adding to the docs site.
 
-To check the generated site you can simply open `docs/index.html` in your favourite browser.
+== Troubleshooting
 
-If you want to make changes to the manual's page structure you'll have to edit
-link:https://github.com/nrepl/nrepl/blob/master/doc/modules/ROOT/nav.adoc[nav.adoc].
+The most common mistake that people make is to forget to update the version of an Antora docs module
+after cutting a release. This will result in an error saying you've got the same version in two branches (e.g. `master`
+and `v1.0`). Fixing this is pretty simple - just update the version to `master` in `antora.yml`.

antora-playbook.yml

@@ -24,4 +24,4 @@ ui:
     snapshot: true
   supplemental_files: ./supplemental-ui
 output:
-  dir: ./docs
+  dir: build/site