fix #695: ci/cd: configure GitHub Pages for docs

.github/workflows/docs.yml

@@ -13,17 +13,51 @@ on:
     paths:
       - '.github/workflows/docs.yml'
       - 'docs/*'
+      - 'tools/pages/*'
+      - 'tools/*.jsx?'
+      - 'tools/package*.json'
     tags: [ '!*' ]
 
 concurrency:
   group: pages
   cancel-in-progress: false
 
 jobs:
+  build:
+    name: Building
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@v3
+        with: { fetch-depth: 0 }
+      - name: Set up Node.js environment
+        uses: actions/setup-node@v3
+        with: { node-version: 16 }
+      - name: Set up GitHub Pages
+        uses: actions/configure-pages@v3
+        with: { static_site_generator: next }
+
+      - name: Cache tooling dependencies
+        id: tools
+        uses: actions/cache@v3
+        with:
+          path: ./tools/node_modules
+          key: tools-${{ hashFiles('tools/package-lock.json') }}
+      - name: Install tooling dependencies if needed
+        run: ./Taskfile docs install
+        if: steps.tools.outputs.cache-hit != 'true'
+
+      - name: Build static HTML with Next.js
+        run: ./Taskfile docs build publish
+      - name: Upload the documentation
+        uses: actions/upload-pages-artifact@v1
+        with: { path: docs }
+
   deploy:
     name: Deploying
+    needs: [ build ]
     runs-on: ubuntu-latest
-    if: github.event_name == 'workflow_dispatch'
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
@@ -33,14 +67,6 @@ jobs:
       pages: write
 
     steps:
-      - name: Checkout the repository
-        uses: actions/checkout@v3
-        with: { fetch-depth: 0 }
-      - name: Set up GitHub Pages
-        uses: actions/configure-pages@v3
-      - name: Upload the documentation
-        uses: actions/upload-pages-artifact@v1
-        with: { path: docs }
       - name: Deploy it to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v2
@@ -61,6 +87,7 @@ jobs:
 
       - name: Send Slack notification
         uses: rtCamp/action-slack-notify@v2
+        continue-on-error: true
         env:
           SLACK_COLOR: ${{ contains(needs.*.result, 'failure') && 'failure' || 'success' }}
           SLACK_FOOTER: made with ❤️ for everyone, OctoLab

Taskfile

@@ -291,6 +291,50 @@ deploy() {
   vercel deploy --yes --prebuilt
 }
 
+# Example: run docs
+# Example: run docs build publish
+function docs() {
+  # dirty hack related to "docker: open .env: no such file or directory"
+  unset -f npm
+
+  pushd tools
+  trap popd EXIT
+
+  local args=("${@}")
+  if [ ${#args[@]} = 0 ]; then
+    args=(install build start)
+  fi
+
+  for arg in "${args[@]}"; do
+    case "${arg}" in
+    install)
+      local lock file=package-lock.json
+      lock=$(dirname "${file}")/node_modules/checksum.lock
+      if [ ! -f "${lock}" ] || [ "$(cat "${lock}")" != "$(md5sum "${file}")" ]; then
+        npm ci
+        md5sum "${file}" >"${lock}"
+      fi
+      ;;
+
+    build)
+      npx --no-install next build
+      ;;
+
+    publish)
+      rm -rf ../docs/*
+      npx --no-install next export -o ../docs
+      git checkout ../docs/redirects ../docs/CNAME
+      ;;
+
+    start)
+      npx --no-install next start
+      ;;
+
+    *) break ;;
+    esac
+  done
+}
+
 whoami() {
   echo "You are $(git config user.name) <$(git config user.email)>"
   echo "* Docker ------------------------------------------"