Set up Antora site

.github/workflows/build.yml

@@ -0,0 +1,46 @@
+name: Build
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version-file: .tool-versions
+          cache: npm
+      - run: npm ci
+      - name: Expose GitHub Actions runtime for the collector-cache Antora extension
+        uses: crazy-max/ghaction-github-runtime@04d248b84655b509d8c44dc1d6f990c879747487 # v4.0.0
+      - run: npm run build
+      - if: github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: build/site
+
+  deploy:
+    if: github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    concurrency:
+      group: pages
+      cancel-in-progress: false
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
+      - id: deploy
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1

.gitignore

@@ -0,0 +1,4 @@
+/build/
+/node_modules/
+/.idea/
+/*.iml

.tool-versions

@@ -0,0 +1 @@
+nodejs 26.13.1

README.md

@@ -0,0 +1,21 @@
+# AssertJ Documentation Site
+
+This branch contains the Antora project for building AssertJ's documentation site.
+
+## Prerequisites
+
+It requires Node.js (for Antora) and Ruby (for asciidoctor.pdf).
+
+A `.tool-versions` file can be used with `asdf` or `mise`:
+
+```
+asdf install # or mise install
+npm install
+bundle install
+```
+
+## Building
+
+```
+npm run build
+```

antora-playbook.yml

@@ -0,0 +1,45 @@
+antora:
+  extensions:
+    - require: './extensions/collector-cache.js'
+    - '@antora/collector-extension'
+    - require: '@antora/lunr-extension'
+      index_by_heading: true
+    - require: '@springio/antora-xref-extension'
+site:
+  title: AssertJ Documentation
+  url: https://docs.assertj.dev
+  robots: allow
+content:
+  sources:
+    - url: .
+      branches: HEAD
+      start_path: home
+asciidoc:
+  sourcemap: true
+  extensions:
+    - '@asciidoctor/tabs'
+  attributes:
+    page-pagination: ''
+    idprefix: '@'
+    idseparator: '-@'
+    table-caption: false
+    table-frame: 'none@'
+    table-grid: 'rows@'
+    table-stripes: 'odd@'
+    figure-caption: false
+    example-caption: false
+    listing-caption: false
+    hide-uri-scheme: '@'
+    attribute-missing: warn
+    tabs-sync-option: ''
+runtime:
+  log:
+    failure_level: warn
+urls:
+  redirect_facility: static
+  latest_version_segment: current
+  latest_prerelease_version_segment: snapshot
+  latest_version_segment_strategy: replace
+ui:
+  bundle:
+    url: https://github.com/assertj/antora-ui/releases/download/20261112-181749/ui-bundle.zip

extensions/cache-scandir/copy-recursive.js

@@ -0,0 +1,29 @@
+// Modified version of https://github.com/spring-io/antora-extensions/blob/fee110d465480db87f029426bfab7da8068e282e/lib/cache-scandir/copy-recursive.js
+// SPDX-License-Identifier: Apache-2.0
+
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+const copyRecursiveSync = function (src, dest) {
+  const exists = fs.existsSync(src)
+  const stats = exists && fs.statSync(src)
+  const isDirectory = exists && stats.isDirectory()
+  if (isDirectory) {
+    if (!fs.existsSync(dest)) {
+      fs.mkdirSync(dest, { recursive: true })
+    }
+    fs.readdirSync(src).forEach(function (childItemName) {
+      copyRecursiveSync(path.join(src, childItemName), path.join(dest, childItemName))
+    })
+  } else {
+    fs.copyFileSync(src, dest)
+  }
+}
+
+function copyRecursive (scanDir, cacheDir) {
+  copyRecursiveSync(scanDir, cacheDir)
+}
+
+module.exports = copyRecursive

extensions/cache-scandir/index.js

@@ -0,0 +1,11 @@
+// Modified version of https://github.com/spring-io/antora-extensions/blob/fee110d465480db87f029426bfab7da8068e282e/lib/cache-scandir/index.js
+// SPDX-License-Identifier: Apache-2.0
+
+'use strict'
+
+const copyRecursive = require('./copy-recursive')
+
+const [, , ...args] = process.argv
+const [scanDir, cacheDir] = args
+
+copyRecursive(scanDir, cacheDir)

extensions/collector-cache.js

@@ -0,0 +1,115 @@
+// Modified version of https://github.com/spring-io/antora-extensions/blob/fee110d465480db87f029426bfab7da8068e282e/lib/inject-collector-cache-config-extension.js
+// SPDX-License-Identifier: Apache-2.0
+
+'use strict'
+
+const expandPath = require('@antora/expand-path-helper')
+const ospath = require('path')
+const resolvedCopyRecursiveJs = require.resolve('./cache-scandir')
+const { createHash } = require('crypto')
+// @actions/cache is ESM-only, so load it via dynamic import from this CommonJS module.
+const cacheLib = import('@actions/cache')
+
+module.exports.register = function ({ playbook, config = {} }) {
+  const logger = this.getLogger('collector-cache')
+  const excludes = config.excludes || []
+  const getUserCacheDir = this.require('cache-directory')
+  const fs = this.require('fs')
+
+  const cacheInfo = []
+  this.once('contentAggregated', async ({ playbook, contentAggregate }) => {
+    const cache = await cacheLib
+    const cacheAvailable = cache.isFeatureAvailable()
+    if (!cacheAvailable) {
+      logger.info('GitHub Actions cache is not available; skipping restore/save operations')
+    }
+    const baseCacheDir = getBaseCacheDir(getUserCacheDir, playbook)
+    for (const { origins } of contentAggregate) {
+      for (const origin of origins) {
+        const { url, gitdir, refhash, worktree, descriptor, refname } = origin
+        const repositoryCacheDirName = generateWorktreeFolderName({ url, gitdir, worktree })
+        const baseCollectorCacheCacheDir = ospath.join(baseCacheDir, 'collector-cache', repositoryCacheDirName)
+        const collectorConfig = descriptor?.ext?.collector
+        if (collectorConfig !== undefined && !excludes.includes(refname)) {
+          const shortref = refhash.slice(0, 7)
+          const cacheDirName = `${shortref}-${refname}`
+          const cacheDir = ospath.join(baseCollectorCacheCacheDir, cacheDirName)
+          const cacheKey = `collector-cache-${repositoryCacheDirName}-${cacheDirName}`
+          if (!fs.existsSync(baseCollectorCacheCacheDir)) {
+            fs.mkdirSync(baseCollectorCacheCacheDir, { recursive: true })
+          }
+          if (cacheAvailable && !fs.existsSync(cacheDir)) {
+            // try and restore from the GitHub Actions cache
+            const restoredKey = await cache.restoreCache([cacheDir], cacheKey).catch((err) => {
+              logger.warn(`Failed to restore cache for key ${cacheKey}: ${err.message}`)
+              return undefined
+            })
+            if (restoredKey) {
+              logger.info(`Successfully restored cache for key ${cacheKey}`)
+            } else {
+              logger.info(`Unable to restore cache for key ${cacheKey}`)
+            }
+          }
+          if (fs.existsSync(cacheDir)) {
+            // use the cache
+            origin.descriptor.ext.collector = {
+              scan: {
+                dir: cacheDir,
+              },
+            }
+            logger.info(`Using the cache found at ${cacheDir}`)
+          } else {
+            const cachedConfig = []
+            const normalizedCollectorConfig = Array.isArray(collectorConfig) ? collectorConfig : [collectorConfig]
+            logger.info(`Configuring collector for caching (url: ${url} | ref: ${refname})`)
+            origin.descriptor.ext.collector = cachedConfig
+            normalizedCollectorConfig.forEach((collector) => {
+              cachedConfig.push(collector)
+              const { scan: scanConfig = [] } = collector
+              const normalizedScanConfigs = Array.isArray(scanConfig) ? scanConfig : [scanConfig]
+              normalizedScanConfigs.forEach((normalizedScanConfig) => {
+                // cache the output of the build
+                const cachedCollectorConfig = createCachedCollectorConfig(normalizedScanConfig.dir, cacheDir, normalizedScanConfig.into)
+                cachedConfig.push.apply(cachedConfig, cachedCollectorConfig)
+              })
+            })
+            if (cacheAvailable) {
+              cacheInfo.push({ cacheDir, cacheKey })
+            }
+          }
+        }
+      }
+    }
+  })
+  this.once('beforePublish', async () => {
+    if (cacheInfo) {
+      const cache = await cacheLib
+      for (const {cacheDir, cacheKey} of cacheInfo) {
+        await cache.saveCache([cacheDir], cacheKey)
+        logger.info(`Saved cache for key ${cacheKey}`)
+      }
+    }
+  })
+}
+
+function getBaseCacheDir (getUserCacheDir, { dir: dot, runtime: { cacheDir: preferredDir } = {} }) {
+  return preferredDir == null
+    ? getUserCacheDir(`antora${process.env.NODE_ENV === 'test' ? '-test' : ''}`) || ospath.join(dot, '.cache/antora')
+    : expandPath(preferredDir, { dot })
+}
+
+function generateWorktreeFolderName ({ url, gitdir, worktree }) {
+  if (worktree === undefined) return ospath.basename(gitdir, '.git')
+  return `${url.substr(url.lastIndexOf('/') + 1)}-${createHash('sha1').update(url).digest('hex')}`
+}
+
+function createCachedCollectorConfig (scanDir, cacheDir, subDir) {
+  return [
+    {
+      run: {
+        command: `\${{env.NODE}} '${resolvedCopyRecursiveJs}' '.' '${cacheDir}${subDir ? `/${subDir}` : ''}'`,
+        dir: scanDir,
+      },
+    },
+  ]
+}

home/antora.yml

@@ -0,0 +1,3 @@
+name: ROOT
+title: AssertJ
+version: ~

home/modules/ROOT/pages/index.adoc

@@ -0,0 +1,3 @@
+= AssertJ Documentation
+
+Welcome to the documentation of https://assertj.github.io/doc/[AssertJ], the fluent assertions library for Java.