refine docs build

- upgrade Antora to 3.2.0-alpha.1
- remove extension (patch) to support linked worktrees
- rename local playbook to local-antora-playbook.yml
- use more precise tags pattern

README.adoc

@@ -75,7 +75,7 @@ SDKMAN will switch to the required JDK or install it if it isn't present.
 This command will build the documentation, including any generated attributes, for the main branch.
 --
 
-. Navigate to _$HOME/spring-security/main/docs/build/site/index.html_ to view the documentation.
+. Navigate to _$HOME/spring-security/main/docs/build/site/index.html_ to view the generated documentation.
 
 [#build-branch]
 == Build the 5.8.x branch documentation (writers)
@@ -104,7 +104,7 @@ Set up a worktree for the 5.8.x branch and then change into the new directory by
 This command will build the documentation, including any generated attributes, for the 5.8.x branch.
 --
 
-. Navigate to _$HOME/spring-security/5.8.x/docs/build/site/index.html_ to view the documentation.
+. Navigate to _$HOME/spring-security/5.8.x/docs/build/site/index.html_ to view the generated documentation.
 
 [#build-production]
 == Build the production documentation site (docs manager)
@@ -130,7 +130,11 @@ Then change into the new _docs-build_ directory.
 --
  $ ./gradlew antora
 
-This command will build all of the documentation included in the project's production site.
+This command will build all of the documentation included in the project's production site from the repository on GitHub.
+
+To build the documentation from the current clone, using any worktrees that are available, use the following command instead:
+
+ $ ./gradlew antora --playbook local-antora-playbook.yml
 --
 
-. Navigate to _$HOME/spring-security/docs-site/build/site/index.html_ to view the documentation.
+. Navigate to _$HOME/spring-security/docs-site/build/site/index.html_ to view the generated documentation.

antora-playbook.yml

@@ -12,10 +12,10 @@ git:
   ensure_git_suffix: false
 content:
   sources:
-    - url: https://github.com/spring-projects/spring-security
-      branches: [main, '5.{{6..9},{1..9}+({0..9})}.x']
-      tags: ['5.{{6..9},{1..9}+({0..9})}.+({0..9})?(-RC{1..9})','{6..9}.*']
-      start_path: docs
+  - url: https://github.com/spring-projects/spring-security
+    branches: [main, '5.{{6..9},{1..9}+({0..9})}.x']
+    tags: ['5.{{6..9},{1..9}+({0..9})}.+({0..9})?(-RC+({0..9}))', '6.+({0..9}).+({0..9})?(-{RC,M}*)']
+    start_path: docs
 asciidoc:
   attributes:
     page-pagination: ''

build.gradle

@@ -4,7 +4,7 @@ plugins {
 }
 
 antora {
-    version = '~3.1'
+    version = '3.2.0-alpha.1'
 	options = ['--clean', '--fetch', '--stacktrace']
 	environment = [
 		'ALGOLIA_API_KEY': '82c7ead946afbac3cf98c32446154691',

lib/antora/extensions/antora-linked-worktree-patch.js

@@ -1,53 +0,0 @@
-'use strict'
-
-/* Copyright (c) 2002-2022 the original author or authors.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- * 
- *   http://www.apache.org/licenses/LICENSE-2.0
- * 
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-const { promises: fsp } = require('fs')
-const ospath = require('path')
-
-/**
- * Rewrites local content sources to support the use of linked worktrees.
- *
- * @author Dan Allen <dan@opendevise.com>
- */
-module.exports.register = function () {
-  this.once('playbookBuilt', async ({ playbook }) => {
-    const expandPath = this.require('@antora/expand-path-helper')
-    for (const contentSource of playbook.content.sources) {
-      const { url, branches } = contentSource
-      if (url.charAt() !== '.') continue
-      const absdir = expandPath(url, { dot: playbook.dir })
-      const gitfile = ospath.join(absdir, '.git')
-      if (await fsp.stat(gitfile).then((stat) => !stat.isDirectory(), () => false)) {
-        const worktreeGitdir = await fsp.readFile(gitfile, 'utf8')
-          .then((contents) => contents.trimRight().substr(8))
-        const worktreeBranch = await fsp.readFile(ospath.join(worktreeGitdir, 'HEAD'), 'utf8')
-          .then((contents) => contents.trimRight().replace(/^ref: (?:refs\/heads\/)?/, ''))
-        const reldir = ospath.relative(
-          playbook.dir,
-          await fsp.readFile(ospath.join(worktreeGitdir, 'commondir'), 'utf8')
-            .then((contents) => {
-              const gitdir = ospath.join(worktreeGitdir, contents.trimRight())
-              return ospath.basename(gitdir) === '.git' ? ospath.dirname(gitdir) : gitdir
-            })
-        )
-        contentSource.url = reldir ? `.${ospath.sep}${reldir}` : '.'
-        if (!branches) continue
-        contentSource.branches = (branches.constructor === Array ? branches : [branches])
-          .map((pattern) => pattern.replaceAll('HEAD', worktreeBranch))
-      }
-    }
-  })
-}

antora-playbook-with-worktrees.yml → local-antora-playbook.yml

@@ -1,6 +1,5 @@
 antora:
   extensions:
-  - ./lib/antora/extensions/antora-linked-worktree-patch.js
   - ./lib/antora/extensions/inject-collector-config.js
   - '@antora/collector-extension'
   - ./lib/antora/extensions/version-fix.js
@@ -8,24 +7,21 @@ antora:
 site:
   title: Spring Security
   url: https://docs.spring.io/spring-security/reference
-  robots: allow
 git:
   ensure_git_suffix: false
 content:
   sources:
-    - url: .
-      branches: [main, '5.{{6..9},{1..9}+({0..9})}.x']
-      worktrees: true # will automatically discover worktrees if they are set up; otherwise, will use git tree
-      tags: '5.{{6..9},{1..9}+({0..9})}.+({0..9})?(-RC{1..9})'
-      start_path: docs
+  - url: .
+    branches: [main, '5.{{6..9},{1..9}+({0..9})}.x']
+    worktrees: true # automatically discovers worktrees, if present; otherwise, will use git tree
+    #tags: ['5.{{6..9},{1..9}+({0..9})}.+({0..9})?(-RC+({0..9}))', '6.+({0..9}).+({0..9})?(-{RC,M}*)']
+    start_path: docs
 asciidoc:
   attributes:
     page-pagination: ''
     hide-uri-scheme: '@'
 urls:
-  latest_version_segment_strategy: redirect:to
   latest_version_segment: ''
-  redirect_facility: httpd
 ui:
   bundle:
     url: https://github.com/spring-io/antora-ui-spring/releases/download/latest/ui-bundle.zip