chore(ci): attempt to build and preview docs

This also isolates the docs build into a workflow that only runs when changes are likely to materially affect doc gen.

.github/workflows/build.yml

@@ -45,21 +45,3 @@ jobs:
         uses: rinchsan/renovate-config-validator@1ea1e8514f6a33fdd71c40b0a5fa3512b9e7b936 # tag=v0
         with:
           pattern: '{.renovaterc.json,renovate/default.json}'
-
-  docs:
-    name: Docs
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3
-      - name: Install dependencies (node)
-        uses: bahmutov/npm-install@1a235c31658a322a3b024444759650ee6345c26d # tag=v1
-        with:
-          useRollingCache: true
-          install-command: npm ci
-      - name: Install dependencies (python)
-        run: pip install -r packages/docutils/requirements.txt
-      - name: Build Docs
-        run: |
-          git config user.name 'Appium Bot'
-          git config user.email 'appium@appium.io'
-          npm run --workspace packages/appium build:docs

.github/workflows/docs.yml

@@ -0,0 +1,40 @@
+name: Build Docs
+
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - closed
+    paths:
+      - './packages/appium/docs/**'
+      - './packages/docutils/**'
+      - './packages/typedoc-plugin-appium/**'
+
+concurrency: preview-${{ github.ref }}
+
+jobs:
+  docs:
+    name: Docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3
+      - name: Install dependencies (node)
+        uses: bahmutov/npm-install@1a235c31658a322a3b024444759650ee6345c26d # tag=v1
+        with:
+          useRollingCache: true
+          install-command: npm ci
+      - name: Install dependencies (python)
+        run: pip install -r packages/docutils/requirements.txt
+      - name: Configure Git User
+        run: |
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+      - name: Build Docs
+        run: npm run docs:preview
+      - name: Deploy Preview
+        if: ${{ github.repository == 'appium/appium' }}
+        uses: rossjrw/pr-preview-action@9dac5c4777c535516ebf819f93aeadac70f66488 # v1
+        with:
+          source-dir: ./packages/appium/docs/site

package.json

@@ -37,6 +37,8 @@
     "clean:workspaces": "lerna clean -y",
     "ci": "npm ci",
     "dev": "run-s \"build -- --watch\"",
+    "docs": "npm run -w packages/appium build:docs",
+    "docs:preview": "npm run -w packages/appium build:docs:preview",
     "doctor": "node ./packages/doctor",
     "husky-install": "husky install",
     "generate-docs": "npm run --workspace=packages/appium generate-docs",

packages/appium/docs/scripts/build-docs.js

@@ -10,7 +10,7 @@
 /* eslint-disable promise/prefer-await-to-callbacks */
 /* eslint-disable promise/prefer-await-to-then */
 
-const {buildReferenceDocs, deploy, updateNav} = require('@appium/docutils');
+const {buildReferenceDocs, deploy, updateNav, buildSite} = require('@appium/docutils');
 const {
   log,
   LANGS,
@@ -28,6 +28,7 @@ const {version} = require('../../package.json');
 const branch = process.env.APPIUM_DOCS_BRANCH ?? DOCS_BRANCH;
 const basePrefix = process.env.APPIUM_DOCS_PREFIX ?? DOCS_PREFIX;
 const remote = process.env.APPIUM_DOCS_REMOTE ?? DOCS_REMOTE;
+const preview = Boolean(process.env.APPIUM_DOCS_PREVIEW);
 
 const push = Boolean(process.env.APPIUM_DOCS_PUBLISH);
 const rebase = push;
@@ -51,17 +52,24 @@ async function main() {
   for (const lang of LANGS) {
     log.info(`Building docs for language '${lang}' and version ${majMinVer}`);
     const configFile = path.join(DOCS_DIR, `mkdocs-${lang}.yml`);
-    await deploy({
-      mkdocsYml: configFile,
-      branch,
-      prefix: path.join(basePrefix, lang),
-      remote,
-      deployVersion: majMinVer,
-      push,
-      alias: LATEST_ALIAS,
-      rebase,
-      message: `docs(appium): auto-build docs for appium@${majMinVer}, language ${lang}`,
-    });
+    if (preview) {
+      await buildSite({
+        mkdocsYml: configFile,
+        siteDir: path.join('site', lang),
+      });
+    } else {
+      await deploy({
+        mkdocsYml: configFile,
+        branch,
+        prefix: path.join(basePrefix, lang),
+        remote,
+        deployVersion: majMinVer,
+        push,
+        alias: LATEST_ALIAS,
+        rebase,
+        message: `docs(appium): auto-build docs for appium@${majMinVer}, language ${lang}`,
+      });
+    }
     log.info(`Docs built`);
   }
 }

packages/appium/package.json

@@ -44,6 +44,7 @@
   ],
   "scripts": {
     "build:docs": "node docs/scripts/build-docs.js",
+    "build:docs:preview": "cross-env APPIUM_DOCS_PREVIEW=1 npm run build:docs",
     "build:docs:assets": "node docs/scripts/copy-assets.js",
     "build:docs:cli": "node docs/scripts/gen-cli-args-docs.js",
     "build:docs:reference": "node docs/scripts/build-reference.js",