feat (docs): Build docs site with GitHub Pages on CI

.github/workflows/ci.yaml

@@ -14,21 +14,29 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-name: Test
+# https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions
+
+name: CI
 
 on:
   push:
-    branches: [main, private]
+    branches: [main]
   pull_request:
     # The branches below must be a subset of the branches above
-    branches: [main, private]
+    branches: [main]
+
+# Cancel any in-progress job or run if there is a newer commit
+concurrency:
+  group: ${{ github.ref }}
+  cancel-in-progress: true
 
 jobs:
-  test:
+  build:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
-        # https://github.com/awalsh128/cache-apt-pkgs-action
+
+        # https://github.com/awalsh128/cache-apt-pkgs-action reduces ~31s to ~2s!
       - uses: awalsh128/cache-apt-pkgs-action@v1.3.0
         with:
           # https://github.com/sharkdp/bat (used in some docs/use/**/script)
@@ -37,7 +45,9 @@ jobs:
           version: 1.0
         # https://github.com/sharkdp/bat/issues/982
       - run: sudo ln -s /usr/bin/batcat /usr/local/bin/bat
-      - uses: actions/cache@v3
+
+      - name: Cache Bazel
+        uses: actions/cache@v3
         with:
           # https://github.com/actions/cache/pull/575/files
           path: |
@@ -47,19 +57,58 @@ jobs:
           key: >
             ${{ runner.os }}-bazel-${{ hashFiles('.bazelversion', '.bazelrc', 'WORKSPACE.bazel', 'MODULE.bazel') }}
           restore-keys: ${{ runner.os }}-bazel-
-      - uses: actions/cache@v3
+      - name: Cache Python
+        uses: actions/cache@v3
         with:
           path: .venv/
           key: ${{ runner.os }}-venv-${{ hashFiles('requirements.txt') }}
           restore-keys: ${{ runner.os }}-venv-
-      - uses: actions/cache@v3
+      - name: Cache Pre-Commit
+        uses: actions/cache@v3
         with:
           path: ~/.cache/pre-commit/
           key: ${{ runner.os }}-cache-${{ hashFiles('.pre-commit-config.yaml') }}
           restore-keys: ${{ runner.os }}-cache-
-      - uses: actions/cache@v3
+      - name: Cache Demo
+        uses: actions/cache@v3
         with:
           path: .cache/demo/
           key: ${{ runner.os }}-cache-demo-${{ hashFiles('demo/test.bash', 'demo/build.bash') }}
           restore-keys: ${{ runner.os }}-cache-demo-
+
       - run: ./test.bash
+
+      # Build docs/ into site/ (not just on main branch but also for pull requests, as test)
+      - name: Build Docs Site
+        run: ./tools/docs/build.bash
+
+      # The following steps deploy site/ (using GitHub Pages)
+      # to https://enola-dev.github.io = https://docs.enola.dev
+
+      - name: Setup Pages
+        if: ${{ github.event_name == 'push' }}
+        uses: actions/configure-pages@v3
+
+      - name: Upload site/ directory as GitHub Pages artifact
+        if: ${{ github.event_name == 'push' }}
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: "site/"
+
+  deploy:
+    needs: build
+    if: ${{ github.event_name == 'push' }}
+    runs-on: ubuntu-latest
+    # https://docs.github.com/en/actions/security-guides/automatic-token-authentication
+    # Sets required permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      # https://github.com/actions/deploy-pages
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

test.bash

@@ -32,9 +32,9 @@ echo
 echo $ b build //...
 bazelisk build //...
 
-# TODO Replace with docs/use/**/BUILD files, so that demo tests only run if inputs change
-# Note use of xargs instead of find -exec \; for error handling, see https://apple.stackexchange.com/a/49047
-find docs/use -maxdepth 1 -not -path docs/use -type d -print0 | xargs -n 1 -0 tools/demo/test.bash
+echo
+echo $ tools/demo/run.bash
+tools/demo/run.bash
 
 # Check if https://pre-commit.com is available (and try to install it not)
 if ! [ -e "./.venv/bin/pre-commit" ]; then
@@ -50,12 +50,18 @@ if ! [ -e "./.venv/bin/pre-commit" ]; then
   fi
   # shellcheck disable=SC1091
   source ./.venv/bin/activate
-  pip install -r requirements.txt
 else
   # shellcheck disable=SC1091
   source ./.venv/bin/activate
 fi
 
+# We need to pip install "every time" (and not just e.g. inside the if above),
+# because otherwise changes to requirements.txt don't lead to updates locally and on CI.
+# TODO Is there a way to only run pip install "if requirements.txt changed"? With Bazel?!
+echo
+echo $ pip install -r requirements.txt
+pip install -r requirements.txt
+
 echo
 echo $ pre-commit run
 pre-commit run

tools/demo/run.bash

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2023 The Enola <https://enola.dev> Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -euo pipefail
+
+# TODO Replace this with docs/use/**/BUILD files, so that demo tests only run if inputs change!
+
+# Note use of xargs instead of find -exec \; for error handling, see https://apple.stackexchange.com/a/49047
+find docs/use -maxdepth 1 -not -path docs/use -type d -print0 | xargs -n 1 -0 tools/demo/test.bash

tools/docs/build.bash

@@ -17,7 +17,7 @@
 
 set -euo pipefail
 
-# This script assumes that ../../test.bash already ran once to set up things!
+# This script assumes that ../../test.bash already ran, to set up tools, and build!
 
 # shellcheck disable=SC1091
 source .venv/bin/activate
@@ -37,18 +37,15 @@ cleanup() {
 }
 trap cleanup EXIT
 
-rpl -R -x.md ../.. https://github.com/enola-dev/enola/blob/main docs/
+# Use sed instead of (ancient) rpl!
+find docs/ -type f -name "*.md" -print0 \
+  | xargs -n 1 -0 sed -i 's|\.\./\.\.|https://github.com/enola-dev/enola/blob/main|g'
 
-bazelisk build //...
 mkdir -p docs/dev/proto/
-cp bazel-bin/core/proto/core_proto_doc/core_proto_doc.md docs/dev/proto/
+cp bazel-bin/core/lib/core_proto_doc/core_proto_doc.md docs/dev/proto/
 
-find docs/use -maxdepth 1 -not -path docs/use -type d -exec tools/demo/build.bash {} \;
+tools/demo/run.bash
 
 # TODO https://github.com/mkdocs/mkdocs/issues/1755
 mkdocs build --strict --config-file mkdocs.yaml
 cleanup
-
-cd site/
-xdg-open http://localhost:8000
-python3 -m http.server

tools/docs/serve-build.bash

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2023 The Enola <https://enola.dev> Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -euo pipefail
+
+./tools/docs/build.bash
+
+cd site/
+xdg-open http://localhost:8000
+python3 -m http.server