feat: Introduce zuul job for building docs

package.json

@@ -30,6 +30,7 @@
     "write-heading-ids": "docusaurus write-heading-ids",
     "typecheck": "tsc",
     "postinstall": "node getDocs.js && node populateStds.js && node populateCerts.js && node populateClouds.js",
+    "postprocess": "node postprocess",
     "test": "echo \"Error: no test specified\" && exit 1",
     "lint:md": "markdownlint-cli2 \"**/*.md\"",
     "fix:md": "markdownlint-cli2-fix \"**/*.md\"",

playbooks/post.yaml

@@ -0,0 +1,6 @@
+- hosts: all
+  tasks:
+    - name: 'Postprocess docusaurus to generate artifacts usable for offline use'
+      ansible.builtin.command: 'npm run postprocess'
+      args:
+        chdir: '{{ zuul.project.src_dir }}'

postprocess.js

@@ -0,0 +1,49 @@
+'use strict'
+
+const fs = require('fs-extra')
+const path = require('path')
+const recursiveReaddir = require('recursive-readdir')
+
+const buildDirectory = path.join(__dirname, 'build')
+const absoluteUrlRegExp = /(href|src)="(?!http[s]|ftp?:\/\/)([^"|#]+)"/g
+
+const isDirectory = (dirPath) => path.extname(dirPath) === ''
+
+const convertAbsolutePathsToRelative = (content, filePath) =>
+  content.replace(absoluteUrlRegExp, (_absoluteUrl, $1, $2) => {
+    const currentDirPath = path.dirname(filePath)
+    const relativeDirPath =
+      currentDirPath === '.' ? '.' : path.relative(currentDirPath, '')
+
+    let relativePath = path.join(relativeDirPath, $2)
+    if (isDirectory(relativePath)) {
+      relativePath = path.join(relativePath, 'index.html')
+    }
+
+    return `${$1}="${relativePath}"`
+  })
+
+const websiteTextualFileExtensions = ['.css', '.js', '.html', '.xml']
+const isNotWebsiteTextualFile = (filePath, stats) =>
+  !(
+    stats.isDirectory() ||
+    websiteTextualFileExtensions.includes(path.extname(filePath))
+  )
+
+const postProcess = async () => {
+  const filePaths = await recursiveReaddir(buildDirectory, [
+    isNotWebsiteTextualFile
+  ])
+  await Promise.all(
+    filePaths.map(async (filePath) => {
+      const content = await fs.readFile(filePath)
+      const relativePath = path.relative(buildDirectory, filePath)
+      await fs.writeFile(
+        filePath,
+        convertAbsolutePathsToRelative(String(content), relativePath)
+      )
+    })
+  )
+}
+
+postProcess()

zuul.yaml

@@ -0,0 +1,18 @@
+---
+- job:
+    name: docs-build
+    parent: js-build
+    nodeset: ubuntu-noble
+    vars:
+      node_version: 18
+      javascript_content_dir: build
+    # pre-run: playbooks/pre.yaml
+    # run: playbooks/run.yaml
+    post-run: playbooks/post.yaml
+
+- project:
+    merge-mode: squash-merge
+    default-branch: main
+    check:
+      jobs:
+        - docs-build