From 20109f8767e342dd59d1260c02b97c355ac86f03 Mon Sep 17 00:00:00 2001 From: Marcus Da Coregio Date: Wed, 15 Feb 2023 14:29:21 -0300 Subject: [PATCH] Update antora Issue gh-2234 --- .idea/checkstyle-idea.xml | 21 +++++------ antora-playbook.yml | 22 ++++++++--- build.gradle | 14 ++++--- .../extensions/inject-collector-config.js | 37 +++++++++++++------ .../extensions/publish-docsearch-config.js | 37 +++++++++++++++++++ .../templates/per-branch-antora-playbook.yml | 35 ++++++++++++++++++ local-antora-playbook.yml | 26 ++++++++----- 7 files changed, 148 insertions(+), 44 deletions(-) create mode 100644 lib/antora/extensions/publish-docsearch-config.js create mode 100644 lib/antora/templates/per-branch-antora-playbook.yml diff --git a/.idea/checkstyle-idea.xml b/.idea/checkstyle-idea.xml index d0a2776f..bc54c74f 100644 --- a/.idea/checkstyle-idea.xml +++ b/.idea/checkstyle-idea.xml @@ -1,16 +1,15 @@ - - \ No newline at end of file diff --git a/antora-playbook.yml b/antora-playbook.yml index 3f333740..b4979e51 100644 --- 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 diff --git a/build.gradle b/build.gradle index 899f6016..8d6cce8b 100644 --- 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', ] } diff --git a/lib/antora/extensions/inject-collector-config.js b/lib/antora/extensions/inject-collector-config.js index 40716769..0a7f8167 100644 --- 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' }, } } } diff --git a/lib/antora/extensions/publish-docsearch-config.js b/lib/antora/extensions/publish-docsearch-config.js new file mode 100644 index 00000000..31388dfa --- /dev/null +++ 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' } }) + }) +} diff --git a/lib/antora/templates/per-branch-antora-playbook.yml b/lib/antora/templates/per-branch-antora-playbook.yml new file mode 100644 index 00000000..2c5d75fd --- /dev/null +++ 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 diff --git a/local-antora-playbook.yml b/local-antora-playbook.yml index c8531714..ebc2901f 100644 --- 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: