Update antora

Issue gh-2234
2023-02-15 14:29:21 -03:00
parent 50720fea6d
commit 20109f8767
7 changed files with 148 additions and 44 deletions
--- a/.idea/checkstyle-idea.xml
+++ b/.idea/checkstyle-idea.xml
@@ -1,16 +1,15 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project version="4">
-  <component name="CheckStyle-IDEA">
-    <option name="configuration">
-      <map>
-        <entry key="checkstyle-version" value="8.45" />
-        <entry key="copy-libs" value="false" />
-        <entry key="location-0" value="BUNDLED:(bundled):Sun Checks" />
-        <entry key="location-1" value="BUNDLED:(bundled):Google Checks" />
-        <entry key="scan-before-checkin" value="false" />
-        <entry key="scanscope" value="JavaOnly" />
-        <entry key="suppress-errors" value="false" />
-      </map>
+  <component name="CheckStyle-IDEA" serialisationVersion="2">
+    <checkstyleVersion>8.45.1</checkstyleVersion>
+    <scanScope>JavaOnly</scanScope>
+    <option name="thirdPartyClasspath" />
+    <option name="activeLocationIds" />
+    <option name="locations">
+      <list>
+        <ConfigurationLocation id="bundled-sun-checks" type="BUNDLED" scope="All" description="Sun Checks">(bundled)</ConfigurationLocation>
+        <ConfigurationLocation id="bundled-google-checks" type="BUNDLED" scope="All" description="Google Checks">(bundled)</ConfigurationLocation>
+      </list>
    </option>
  </component>
 </project>
--- a/antora-playbook.yml
+++ b/antora-playbook.yml
@@ -1,9 +1,17 @@
 antora:
  extensions:
-  - ./lib/antora/extensions/inject-collector-config.js
-  - '@antora/collector-extension'
-  - ./lib/antora/extensions/version-fix.js
-  - '@opendevise/antora-release-line-extension'
+    - '@springio/antora-extensions/partial-build-extension'
+    - ./lib/antora/extensions/inject-collector-config.js
+    - '@antora/collector-extension'
+    - ./lib/antora/extensions/version-fix.js
+    - '@antora/atlas-extension'
+    - '@opendevise/antora-release-line-extension'
+    - require: '@springio/antora-extensions/tabs-migration-extension'
+      # uncomment this option to save the migrated content to the worktree
+      #save_result: true
+      unwrap_example_block: always
+    - require: ./lib/antora/extensions/publish-docsearch-config
+      template_path: ./.github/actions/docsearch-config.json.hbs
 site:
  title: Spring Session
  url: https://docs.spring.io/spring-session/reference
@@ -20,6 +28,10 @@ asciidoc:
  attributes:
    page-pagination: ''
    hide-uri-scheme: '@'
+    tabs-sync-option: '@'
+  extensions:
+    - '@asciidoctor/tabs'
+    - '@springio/asciidoctor-extensions'
 urls:
  latest_version_segment_strategy: redirect:to
  latest_version_segment: ''
@@ -28,5 +40,3 @@ ui:
  bundle:
    url: https://github.com/spring-io/antora-ui-spring/releases/download/latest/ui-bundle.zip
    snapshot: true
-runtime:
-  cache_dir: ./.cache/antora
--- a/build.gradle
+++ b/build.gradle
@@ -1,18 +1,22 @@
 plugins {
 	id 'base'
-	id 'org.antora' version '1.0.0-alpha.3'
+	id 'org.antora' version '1.0.0'
 }

 antora {
-    version = '3.2.0-alpha.1'
-	options = ['--clean', '--fetch', '--stacktrace']
+    version = '3.2.0-alpha.2'
+	options = [clean: true, fetch: true, stacktrace: true]
 	environment = [
 		'ALGOLIA_API_KEY': '82c7ead946afbac3cf98c32446154691',
 		'ALGOLIA_APP_ID': '244V8V9FGG',
 		'ALGOLIA_INDEX_NAME': 'session-docs'
    ]
 	dependencies = [
-		'@antora/collector-extension': '1.0.0-alpha.3',
-		'@opendevise/antora-release-line-extension': '1.0.0-alpha.1'
+			'@antora/atlas-extension': '1.0.0-alpha.1',
+			'@antora/collector-extension': '1.0.0-alpha.3',
+			'@asciidoctor/tabs': '1.0.0-beta.3',
+			'@opendevise/antora-release-line-extension': '1.0.0',
+			'@springio/antora-extensions': '1.0.0',
+			'@springio/asciidoctor-extensions': '1.0.0-alpha.8',
 	]
 }
--- a/lib/antora/extensions/inject-collector-config.js
+++ b/lib/antora/extensions/inject-collector-config.js
@@ -1,25 +1,38 @@
 'use strict'

-const BASE_COMMAND = 'gradlew -PbuildSrc.skipTests=true'
+const BASE_COMMAND = 'gradlew -PbuildSrc.skipTests=true -Porg.gradle.java.installations.auto-detect=false --scan --stacktrace'
 const JVM_ARGS='-Xmx3g -XX:+HeapDumpOnOutOfMemoryError'
 const REPO_URL = 'https://github.com/spring-projects/spring-session'
 const TASK_NAME=':spring-session-docs:generateAntora'

+/**
+ * Set of tags that contain a collector config, but the antora command fails on GitHub Actions.
+ */
+const VERSIONS_TO_OVERRIDE = [
+  '6.0.0-RC1'
+]
+
+/**
+ * The purpose of this extension is to inject the Antora Collector configuration into the parsed component version
+ * descriptor in tags created before Antora Collector was introduced. Antora Collector runs a command to generate a
+ * replacement antora.yml that a) sets the version from the value of the version property in gradle.properties and b)
+ * populates AsciiDoc attributes with information from the Gradle build, such as software versions and resource URLs.
+ */
 module.exports.register = function () {
  this.once('contentAggregated', ({ contentAggregate }) => {
    for (const { origins } of contentAggregate) {
      for (const origin of origins) {
-        if (origin.url === REPO_URL && origin.descriptor.ext?.collector === undefined) {
-          origin.descriptor.ext = {
-            collector: [{
-              run: {
-                command: `${BASE_COMMAND} "-Dorg.gradle.jvmargs=${JVM_ARGS}" ${TASK_NAME} --stacktrace --no-build-cache --no-configuration-cache --no-daemon`,
-                local: true,
-              },
-              scan: {
-                dir: './build/generateAntora',
-              },
-            }]
+        if (origin.url !== REPO_URL) {
+          continue
+        }
+        // Ignore tags with their own collector config unless the antora command fails on GitHub Actions
+        if (!(origin.descriptor.ext?.collector === undefined || VERSIONS_TO_OVERRIDE.includes(origin.tag))) {
+          continue
+        }
+        origin.descriptor.ext = {
+          collector: {
+            run: { command: `${BASE_COMMAND} "-Dorg.gradle.jvmargs=${JVM_ARGS}" ${TASK_NAME}`, local: true },
+            scan: { dir: './build/generateAntora' },
          }
        }
      }
--- a/lib/antora/extensions/publish-docsearch-config.js
+++ b/lib/antora/extensions/publish-docsearch-config.js
@@ -0,0 +1,37 @@
+'use strict'
+
+const fsp = require('node:fs/promises')
+const ospath = require('node:path')
+
+/**
+ * An Antora extension that generates a config file that controls the behavior of the docsearch scraper.
+ *
+ * This extension generates a docsearch config file by evaluating a Handlebars template (e.g.,
+ * .github/actions/docsearch-config.json.hbs). It then publishes the output file to the root of the site
+ * (docsearch-config.json). The docsearch scraper will retrieve for the config file from the published site.
+ *
+ * This extension will only add entries for the latest version in each release line. Additionally, if the page-archived
+ * or page-noindex attribute is defined in the document header of the page, that page will be excluded from the index.
+ */
+module.exports.register = function ({ config: { templatePath = './docsearch/config.json.hbs' } }) {
+    const expandPath = this.require('@antora/expand-path-helper')
+    const handlebars = this.require('handlebars').create()
+    handlebars.registerHelper('eq', (a, b) => a === b)
+    handlebars.registerHelper('and', (a, b) => a && b)
+
+    this.on('beforePublish', async ({ playbook, contentCatalog, siteCatalog }) => {
+        templatePath = expandPath(templatePath, { dot: playbook.dir })
+        const templateSrc = await fsp.readFile(templatePath, 'utf8')
+        const templateBasename = ospath.basename(templatePath)
+        const template = handlebars.compile(templateSrc, { noEscape: true, preventIndent: true, srcName: templateBasename })
+        const latestVersions = contentCatalog.getComponentsSortedBy('name').reduce((accum, component) => {
+            component.versions.forEach((version) => version.versionSegment !== undefined && accum.push(version))
+            return accum
+        }, [])
+        const stopPages = contentCatalog.getPages((page) => {
+            return page.out && ('page-archived' in page.asciidoc.attributes || 'page-noindex' in page.asciidoc.attributes)
+        })
+        const compiled = template({ latestVersions, site: playbook.site, stopPages })
+        siteCatalog.addFile({ contents: Buffer.from(compiled), out: { path: 'docsearch-config.json' } })
+    })
+}
--- a/lib/antora/templates/per-branch-antora-playbook.yml
+++ b/lib/antora/templates/per-branch-antora-playbook.yml
@@ -0,0 +1,35 @@
+# PACKAGES antora@3.2.0-alpha.2 @antora/atlas-extension:1.0.0-alpha.1 @antora/collector-extension@1.0.0-alpha.3 @springio/antora-extensions@1.0.0 @asciidoctor/tabs@1.0.0-beta.3 @opendevise/antora-release-line-extension@1.0.0
+#
+# The purpose of this Antora playbook is to build the docs in the current branch.
+antora:
+  extensions:
+    - '@antora/collector-extension'
+    - id: '@antora/atlas-extension'
+      require: '@antora/atlas-extension'
+      enabled: false
+    - '@opendevise/antora-release-line-extension'
+    - require: '@springio/antora-extensions/tabs-migration-extension'
+      unwrap_example_block: always
+site:
+  title: Spring Session Reference
+content:
+  sources:
+    - url: ./..
+      branches: HEAD
+      start_path: docs
+      worktrees: true
+asciidoc:
+  attributes:
+    hide-uri-scheme: '@'
+    page-pagination: ''
+    primary-site-url: https://docs.spring.io/spring-session/reference
+    tabs-sync-option: '@'
+  extensions:
+    - '@asciidoctor/tabs'
+  sourcemap: true
+urls:
+  latest_version_segment: ''
+ui:
+  bundle:
+    url: https://github.com/spring-io/antora-ui-spring/releases/download/latest/ui-bundle.zip
+    snapshot: true
--- a/local-antora-playbook.yml
+++ b/local-antora-playbook.yml
@@ -1,25 +1,31 @@
 antora:
  extensions:
-  - ./lib/antora/extensions/inject-collector-config.js
-  - '@antora/collector-extension'
-  - ./lib/antora/extensions/version-fix.js
-  - '@opendevise/antora-release-line-extension'
+    - ./lib/antora/extensions/inject-collector-config.js
+    - '@antora/collector-extension'
+    - ./lib/antora/extensions/version-fix.js
+    - '@opendevise/antora-release-line-extension'
+    - require: '@springio/antora-extensions/tabs-migration-extension'
+      # uncomment this option to save the migrated content to the worktree
+      #save_result: true
+      unwrap_example_block: always
 site:
-  title: Spring Session
-  url: https://docs.spring.io/spring-session/reference
-git:
-  ensure_git_suffix: false
+  title: Spring Security
+  url: https://docs.spring.io/spring-security/reference
 content:
  sources:
  - url: .
-    branches: [ main, '2.{6..9}+.{0..9}+.x' ]
-    tags: [ '2.{6..9}.*', '3.+({0..9}).+({0..9})?(-{RC,M}*)', '!2.6.0-M*','!2.6.0-RC*','!2.7.0-M1','!3.0.0-M1' ]
+    branches: [ main, '2.{6..9}+.{0..9}+.x']
+    tags: [ '2.{6..9}.*', '3.+({0..9}).+({0..9})?(-{RC,M}*)?', '!2.6.0-M*','!2.6.0-RC*','!2.7.0-M1','!3.0.0-M1' ]
    start_path: spring-session-docs
    worktrees: true # automatically discovers worktrees, if present; otherwise, will use git tree
 asciidoc:
  attributes:
    page-pagination: ''
    hide-uri-scheme: '@'
+    tabs-sync-option: '@'
+  extensions:
+    - '@asciidoctor/tabs'
+    - '@springio/asciidoctor-extensions'
 urls:
  latest_version_segment: ''
 ui: