Migrate User Guide and Release Notes to Antora

.github/workflows/main.yml

@@ -122,26 +122,15 @@ jobs:
       run: |
         sudo apt-get update
         sudo apt-get install graphviz
-    - name: Build Documentation
-      uses: ./.github/actions/run-gradle
+    - name: Install Node.js
+      uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
       with:
-        encryptionKey: ${{ secrets.GRADLE_ENCRYPTION_KEY }}
-        arguments: |
-          prepareDocsForUploadToGhPages \
-          -Dscan.tag.Documentation
-    - name: Configure Git
-      shell: bash
-      run: |
-        git config --global user.name "JUnit Team"
-        git config --global user.email "[email protected]"
-    - name: Upload Documentation
-      if: github.event_name == 'push' && github.repository == 'junit-team/junit-framework' && github.ref == 'refs/heads/main'
+        node-version-file: documentation/.tool-versions
+    - name: Build Documentation
       uses: ./.github/actions/run-gradle
       with:
         encryptionKey: ${{ secrets.GRADLE_ENCRYPTION_KEY }}
         arguments: |
-          gitPublishPush \
+          antora \
+          -Pantora.downloadNode=false \
           -Dscan.tag.Documentation
-      env:
-        GIT_USERNAME: git
-        GIT_PASSWORD: ${{ secrets.JUNIT_BUILDS_GITHUB_TOKEN_DOCS_REPO }}

.github/zizmor.yml

@@ -0,0 +1,5 @@
+rules:
+  cache-poisoning:
+    ignore:
+      # reports issues for setup-node which isn't used while releasing
+      - main.yml

.gitignore

@@ -38,3 +38,6 @@ checksums*
 # snapshot-tests
 *.snapshot_actual
 *.snapshot_raw
+
+# Antora
+/documentation/node_modules/

documentation/.tool-versions

@@ -0,0 +1 @@
+nodejs 24.11.1

documentation/README.md

@@ -1,34 +1,25 @@
 # JUnit User Guide
 
-This subproject contains the AsciiDoc sources for the JUnit User Guide.
+This subproject contains the Antora/AsciiDoc sources for the JUnit User Guide.
 
 ## Structure
 
-- `src/docs/asciidoc`: AsciiDoc files
+- `modules/ROOT/pages`: AsciiDoc files
 - `src/test/java`: Java test source code that can be included in the AsciiDoc files
 - `src/test/kotlin`: Kotlin test source code that can be included in the AsciiDoc files
 - `src/test/resources`: Classpath resources that can be included in the AsciiDoc files or
   used in tests
 
 ## Usage
 
-### Generate AsciiDoc
+### Generate Antora site
 
 This following Gradle command generates the HTML version of the User Guide as
-`build/docs/asciidoc/user-guide/index.html`.
+`build/antora/build/site`.
 
 ```
-./gradlew asciidoctor
+./gradlew antora
 ```
 
 On Linux operating systems, the `graphviz` package providing `/usr/bin/dot` must be
-installed in order to generate the User Guide.
-
-### Generate AsciiDocPdf
-
-This following Gradle command generates the PDF version of the User Guide to
-`build/docs/asciidocPdf/user-guide/index.pdf`.
-
-```
-./gradlew asciidoctorPdf
-```
+installed in order to generate the PlantUML images used in the User Guide.

documentation/antora-playbook.yml

@@ -0,0 +1,26 @@
+antora:
+  extensions:
+  - '@antora/collector-extension'
+  - '@antora/lunr-extension'
+  - require: '@springio/antora-extensions/root-component-extension'
+    root_component_name: junit
+  - require: '@springio/antora-extensions/root-attachments-extension'
+site:
+  title: JUnit User Guide
+  url: https://docs.junit.org
+content:
+  sources:
+  - url: @GIT_REPO_ROOT@
+    branches: @GIT_BRANCH_NAME@
+    start_path: documentation
+    worktrees: true
+asciidoc:
+  attributes:
+    attribute-missing: warn
+runtime:
+  log:
+    failure_level: warn
+ui:
+  bundle:
+    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
+    snapshot: true

documentation/documentation.gradle.kts

@@ -5,16 +5,11 @@ import junitbuild.exec.RunConsoleLauncher
 import junitbuild.extensions.isSnapshot
 import junitbuild.extensions.javaModuleName
 import junitbuild.javadoc.ModuleSpecificJavadocFileOption
-import org.asciidoctor.gradle.base.AsciidoctorAttributeProvider
-import org.asciidoctor.gradle.jvm.AbstractAsciidoctorTask
 import org.gradle.api.tasks.PathSensitivity.RELATIVE
-import org.ysb33r.grolifant.api.core.jvm.ExecutionMode.JAVA_EXEC
 
 plugins {
-	alias(libs.plugins.asciidoctorConvert)
-	alias(libs.plugins.asciidoctorPdf)
-	alias(libs.plugins.gitPublish)
 	alias(libs.plugins.plantuml)
+	id("junitbuild.antora-conventions")
 	id("junitbuild.build-parameters")
 	id("junitbuild.kotlin-library-conventions")
 	id("junitbuild.testing-conventions")
@@ -84,14 +79,6 @@ dependencies {
 	standaloneConsoleLauncher(projects.junitPlatformConsoleStandalone)
 }
 
-asciidoctorj {
-	setJrubyVersion(libs.versions.jruby)
-	modules {
-		pdf.version(libs.versions.asciidoctorj.pdf)
-	}
-	requires(file("src/docs/asciidoc/resources/themes/rouge_junit.rb"))
-}
-
 val buildRevision: String by rootProject.extra
 val snapshot = version.isSnapshot()
 val docsVersion = if (snapshot) "snapshot" else version
@@ -103,30 +90,6 @@ val userGuidePdfFileName = "junit-user-guide-${version}.pdf"
 val ota4jDocVersion = libs.versions.opentest4j.map { if (it.isSnapshot()) "snapshot" else it }.get()
 val apiGuardianDocVersion = libs.versions.apiguardian.map { if (it.isSnapshot()) "snapshot" else it }.get()
 
-gitPublish {
-	repoUri = "https://github.com/junit-team/docs.junit.org.git"
-
-	branch = "main"
-	sign = false
-	fetchDepth = 1
-
-	username = providers.environmentVariable("GIT_USERNAME")
-	password = providers.environmentVariable("GIT_PASSWORD")
-
-	contents {
-		from(docsDir)
-		into(".")
-	}
-
-	preserve {
-		include("**/*")
-		exclude("$docsVersion/**")
-		if (replaceCurrentDocs) {
-			exclude("current/**")
-		}
-	}
-}
-
 val generatedAsciiDocPath = layout.buildDirectory.dir("generated/asciidoc")
 val consoleLauncherOptionsFile = generatedAsciiDocPath.map { it.file("console-launcher-options.txt") }
 val consoleLauncherDiscoverOptionsFile = generatedAsciiDocPath.map { it.file("console-launcher-discover-options.txt") }
@@ -270,8 +233,8 @@ tasks {
 
 	val plantUmlOutputDirectory = plantUml.flatMap { it.outputDirectory }
 
-	withType<AbstractAsciidoctorTask>().configureEach {
-		inputs.files(
+	val generateAsciidocInputs by registering {
+		dependsOn(
 			generateConsoleLauncherOptions,
 			generateConsoleLauncherDiscoverOptions,
 			generateConsoleLauncherExecuteOptions,
@@ -280,100 +243,6 @@ tasks {
 			generateStandaloneConsoleLauncherShadowedArtifactsFile,
 			plantUmlOutputDirectory
 		)
-
-		resources {
-			from(sourceDir) {
-				include("**/images/**/*.png")
-				include("**/images/**/*.svg")
-			}
-			from(plantUmlOutputDirectory) {
-				into("user-guide/images")
-			}
-		}
-
-		// Temporary workaround for https://github.com/asciidoctor/asciidoctor-gradle-plugin/issues/599
-		inputs.dir(sourceDir).withPropertyName("sourceDir").withPathSensitivity(RELATIVE)
-
-		attributeProviders += AsciidoctorAttributeProvider {
-			mapOf(
-				"version" to version,
-				"junit4-version" to libs.versions.junit4.get(),
-				"apiguardian-version" to libs.versions.apiguardian.get(),
-				"ota4j-version" to libs.versions.opentest4j.get(),
-				"surefire-version" to libs.versions.surefire.get(),
-				"release-branch" to releaseBranch,
-				"docs-version" to docsVersion,
-				"revnumber" to version,
-				"consoleLauncherOptionsFile" to consoleLauncherOptionsFile.get(),
-				"consoleLauncherDiscoverOptionsFile" to consoleLauncherDiscoverOptionsFile.get(),
-				"consoleLauncherExecuteOptionsFile" to consoleLauncherExecuteOptionsFile.get(),
-				"consoleLauncherEnginesOptionsFile" to consoleLauncherEnginesOptionsFile.get(),
-				"experimentalApisTableFile" to experimentalApisTableFile.get(),
-				"deprecatedApisTableFile" to deprecatedApisTableFile.get(),
-				"standaloneConsoleLauncherShadowedArtifactsFile" to standaloneConsoleLauncherShadowedArtifactsFile.get(),
-				"outdir" to outputDir.absolutePath,
-				"source-highlighter" to "rouge",
-				"rouge-style" to "junit",
-				"tabsize" to "4",
-				"toc" to "left",
-				"icons" to "font",
-				"sectanchors" to true,
-				"idprefix" to "",
-				"idseparator" to "-",
-				"jdk-javadoc-base-url" to jdkJavadocBaseUrl
-			)
-		}
-
-		sourceSets["test"].apply {
-			attributes(mapOf(
-					"testDir" to java.srcDirs.first(),
-					"testResourcesDir" to resources.srcDirs.first()
-			))
-			inputs.dir(java.srcDirs.first())
-			inputs.dir(resources.srcDirs.first())
-			attributes(mapOf("kotlinTestDir" to kotlin.srcDirs.first()))
-			inputs.dir(kotlin.srcDirs.first())
-		}
-
-		jvm {
-			// To avoid warning, see https://github.com/asciidoctor/asciidoctor-gradle-plugin/issues/597
-			jvmArgs(
-				"--add-opens", "java.base/sun.nio.ch=ALL-UNNAMED",
-				"--add-opens", "java.base/java.io=ALL-UNNAMED"
-			)
-		}
-
-		notCompatibleWithConfigurationCache("https://github.com/asciidoctor/asciidoctor-gradle-plugin/issues/564")
-	}
-
-	asciidoctor {
-		sources {
-			include("**/index.adoc")
-		}
-		resources {
-			from(sourceDir) {
-				include("tocbot-*/**")
-			}
-		}
-		attributes(mapOf(
-				"linkToPdf" to uploadPdfs,
-				"userGuidePdfFileName" to userGuidePdfFileName,
-				"releaseNotesUrl" to "../release-notes/index.html#release-notes"
-		))
-	}
-
-	asciidoctorPdf {
-		// Avoid classpath conflicts with other Gradle plugins (e.g. JReleaser)
-		// Avoid propagating apparent memory leaks in Asciidoctor/JRuby to Gradle daemon.
-		setExecutionMode(JAVA_EXEC)
-		jvm {
-			maxHeapSize = "512M"
-		}
-		sources {
-			include("user-guide/index.adoc")
-		}
-		copyAllResources()
-		attributes(mapOf("releaseNotesUrl" to "https://docs.junit.org/$docsVersion/release-notes/"))
 	}
 
 	val downloadJavadocElementLists by registering {
@@ -496,58 +365,28 @@ tasks {
 		into(layout.buildDirectory.dir("docs/fixedJavadoc"))
 	}
 
-	val prepareDocsForUploadToGhPages by registering(Copy::class) {
-		dependsOn(fixJavadoc, asciidoctor, asciidoctorPdf)
-		outputs.dir(docsDir)
-
-		from(asciidoctor.map { it.outputDir }) {
-			include("user-guide/**")
-			include("release-notes/**")
-			include("tocbot-*/**")
-		}
-		if (uploadPdfs) {
-			from(asciidoctorPdf.map { it.outputDir }) {
-				include("**/*.pdf")
-				rename { userGuidePdfFileName }
-			}
-		}
-		from(fixJavadoc.map { it.destinationDir }) {
-			into("api")
-		}
-		into(docsDir.map { it.dir(docsVersion.toString()) })
-		includeEmptyDirs = false
-	}
-
-	val createCurrentDocsFolder by registering(Copy::class) {
-		dependsOn(prepareDocsForUploadToGhPages)
-		onlyIf { replaceCurrentDocs }
-
-		from(docsDir.map { it.dir(docsVersion.toString()) })
-		into(docsDir.map { it.dir("current") })
-	}
-
-	val configureGitAuthor by registering {
-		dependsOn(gitPublishReset)
-		doFirst {
-			File(gitPublish.repoDir.get().asFile, ".git/config").appendText("""
-				[user]
-					name = JUnit Team
-					email = [email protected]
-			""".trimIndent())
-		}
-	}
-
-	gitPublishCopy {
-		dependsOn(prepareDocsForUploadToGhPages, createCurrentDocsFolder)
-	}
-
-	gitPublishCommit {
-		dependsOn(configureGitAuthor)
-	}
-
 	val prepareGitHubAttestation by registering(Sync::class) {
 		from(attestationClasspath)
 		into(layout.buildDirectory.dir("attestation"))
 		rename("(.*)-SNAPSHOT.jar", "$1-SNAPSHOT+${buildRevision.substring(0, 7)}.jar")
 	}
+
+	generateAntoraYml {
+		asciidocAttributes.putAll(provider {
+			mapOf(
+				"version" to project.version,
+				"junit4-version" to libs.versions.junit4.get(),
+				"apiguardian-version" to libs.versions.apiguardian.get(),
+				"ota4j-version" to libs.versions.opentest4j.get(),
+				"surefire-version" to libs.versions.surefire.get(),
+				"release-branch" to releaseBranch,
+				"docs-version" to docsVersion,
+				"jdk-javadoc-base-url" to jdkJavadocBaseUrl
+			)
+		})
+	}
+
+	generateAntoraResources {
+		dependsOn(generateAsciidocInputs, fixJavadoc)
+	}
 }