Migrate to asciidoctor-spring-backends

Migrate to the snapshot version of asciidoctor-spring-backends.

See gh-25553

Author: philwebb

buildSrc/build.gradle

@@ -18,8 +18,8 @@ dependencies {
 	implementation("com.fasterxml.jackson.core:jackson-databind:2.11.4")
 	implementation("commons-codec:commons-codec:1.13")
 	implementation("org.apache.maven:maven-embedder:3.6.2")
-	implementation("org.asciidoctor:asciidoctor-gradle-jvm:3.0.0")
-	implementation("org.asciidoctor:asciidoctor-gradle-jvm-pdf:3.0.0")
+	implementation("org.asciidoctor:asciidoctor-gradle-jvm:3.1.0")
+	implementation("org.asciidoctor:asciidoctor-gradle-jvm-pdf:3.1.0")
 	implementation("org.gradle:test-retry-gradle-plugin:1.1.9")
 	implementation("org.springframework:spring-core:5.2.2.RELEASE")
 	implementation("org.springframework:spring-web:5.2.2.RELEASE")

buildSrc/src/main/java/org/springframework/boot/build/AsciidoctorConventions.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019-2020 the original author or authors.
+ * Copyright 2019-2021 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.
@@ -26,16 +26,10 @@
 import org.asciidoctor.gradle.jvm.AsciidoctorJExtension;
 import org.asciidoctor.gradle.jvm.AsciidoctorJPlugin;
 import org.asciidoctor.gradle.jvm.AsciidoctorTask;
-import org.gradle.api.Action;
-import org.gradle.api.DefaultTask;
 import org.gradle.api.Project;
-import org.gradle.api.Task;
 import org.gradle.api.artifacts.Configuration;
-import org.gradle.api.file.FileCollection;
-import org.gradle.api.tasks.InputFiles;
-import org.gradle.api.tasks.OutputDirectory;
+import org.gradle.api.artifacts.ConfigurationContainer;
 import org.gradle.api.tasks.Sync;
-import org.gradle.api.tasks.TaskAction;
 
 import org.springframework.boot.build.artifactory.ArtifactoryRepository;
 import org.springframework.util.StringUtils;
@@ -46,15 +40,13 @@
  *
  * <ul>
  * <li>All warnings are made fatal.
- * <li>The version of AsciidoctorJ is upgraded to 2.4.1.
- * <li>A task is created to resolve and unzip our documentation resources (CSS and
- * Javascript).
+ * <li>The version of AsciidoctorJ is upgraded to 2.4.3.
+ * <li>A {@code asciidoctorExtensions} configuration is created.
  * <li>For each {@link AsciidoctorTask} (HTML only):
  * <ul>
  * <li>A task is created to sync the documentation resources to its output directory.
  * <li>{@code doctype} {@link AsciidoctorTask#options(Map) option} is configured.
- * <li>{@link AsciidoctorTask#attributes(Map) Attributes} are configured for syntax
- * highlighting, CSS styling, docinfo, etc.
+ * <li>The {@code backend} is configured.
  * </ul>
  * <li>For each {@link AbstractAsciidoctorTask} (HTML and PDF):
  * <ul>
@@ -70,43 +62,25 @@
  */
 class AsciidoctorConventions {
 
-	private static final String ASCIIDOCTORJ_VERSION = "2.4.1";
+	private static final String EXTENSIONS_CONFIGURATION = "asciidoctorExtensions";
+
+	private static final String ASCIIDOCTORJ_VERSION = "2.4.3";
 
 	void apply(Project project) {
 		project.getPlugins().withType(AsciidoctorJPlugin.class, (asciidoctorPlugin) -> {
 			configureDocResourcesRepository(project);
 			makeAllWarningsFatal(project);
 			upgradeAsciidoctorJVersion(project);
-			UnzipDocumentationResources unzipResources = createUnzipDocumentationResourcesTask(project);
-			project.getTasks().withType(AbstractAsciidoctorTask.class, (asciidoctorTask) -> {
-				configureCommonAttributes(project, asciidoctorTask);
-				configureOptions(asciidoctorTask);
-				asciidoctorTask.baseDirFollowsSourceDir();
-				Sync syncSource = createSyncDocumentationSourceTask(project, asciidoctorTask);
-				if (asciidoctorTask instanceof AsciidoctorTask) {
-					configureHtmlOnlyAttributes(asciidoctorTask);
-					syncSource.from(unzipResources, (resources) -> resources.into("asciidoc"));
-					asciidoctorTask.doFirst(new Action<Task>() {
-
-						@Override
-						public void execute(Task task) {
-							project.copy((spec) -> {
-								spec.from(asciidoctorTask.getSourceDir());
-								spec.into(asciidoctorTask.getOutputDir());
-								spec.include("css/**", "js/**");
-							});
-						}
-
-					});
-				}
-			});
+			createAsciidoctorExtensionsConfiguration(project);
+			project.getTasks().withType(AbstractAsciidoctorTask.class,
+					(asciidoctorTask) -> configureAsciidoctorTask(project, asciidoctorTask));
 		});
 	}
 
 	private void configureDocResourcesRepository(Project project) {
 		project.getRepositories().maven((mavenRepo) -> {
-			mavenRepo.setUrl(URI.create("https://repo.spring.io/release"));
-			mavenRepo.mavenContent((mavenContent) -> mavenContent.includeGroup("io.spring.docresources"));
+			mavenRepo.setUrl(URI.create("https://repo.spring.io/snapshot"));
+			mavenRepo.mavenContent((mavenContent) -> mavenContent.includeGroup("io.spring.asciidoctor.backends"));
 		});
 	}
 
@@ -118,41 +92,26 @@ private void upgradeAsciidoctorJVersion(Project project) {
 		project.getExtensions().getByType(AsciidoctorJExtension.class).setVersion(ASCIIDOCTORJ_VERSION);
 	}
 
-	private UnzipDocumentationResources createUnzipDocumentationResourcesTask(Project project) {
-		Configuration documentationResources = project.getConfigurations().maybeCreate("documentationResources");
-		documentationResources.getDependencies()
-				.add(project.getDependencies().create("io.spring.docresources:spring-doc-resources:0.2.5"));
-		UnzipDocumentationResources unzipResources = project.getTasks().create("unzipDocumentationResources",
-				UnzipDocumentationResources.class);
-		unzipResources.setResources(documentationResources);
-		unzipResources.setOutputDir(new File(project.getBuildDir(), "docs/resources"));
-		return unzipResources;
-	}
-
-	private Sync createSyncDocumentationSourceTask(Project project, AbstractAsciidoctorTask asciidoctorTask) {
-		Sync syncDocumentationSource = project.getTasks()
-				.create("syncDocumentationSourceFor" + StringUtils.capitalize(asciidoctorTask.getName()), Sync.class);
-		File syncedSource = new File(project.getBuildDir(), "docs/src/" + asciidoctorTask.getName());
-		syncDocumentationSource.setDestinationDir(syncedSource);
-		syncDocumentationSource.from("src/docs/");
-		asciidoctorTask.dependsOn(syncDocumentationSource);
-		asciidoctorTask.setSourceDir(project.relativePath(new File(syncedSource, "asciidoc/")));
-		return syncDocumentationSource;
-	}
-
-	private void configureOptions(AbstractAsciidoctorTask asciidoctorTask) {
-		asciidoctorTask.options(Collections.singletonMap("doctype", "book"));
+	private void createAsciidoctorExtensionsConfiguration(Project project) {
+		ConfigurationContainer configurations = project.getConfigurations();
+		Configuration asciidoctorExtensions = configurations.maybeCreate(EXTENSIONS_CONFIGURATION);
+		asciidoctorExtensions.getDependencies().add(project.getDependencies()
+				.create("io.spring.asciidoctor.backends:asciidoctor-spring-backends:0.0.1-SNAPSHOT"));
+		Configuration dependencyManagement = configurations.findByName("dependencyManagement");
+		if (dependencyManagement != null) {
+			asciidoctorExtensions.extendsFrom(dependencyManagement);
+		}
 	}
 
-	private void configureHtmlOnlyAttributes(AbstractAsciidoctorTask asciidoctorTask) {
-		Map<String, Object> attributes = new HashMap<>();
-		attributes.put("source-highlighter", "highlightjs");
-		attributes.put("highlightjsdir", "js/highlight");
-		attributes.put("highlightjs-theme", "github");
-		attributes.put("linkcss", true);
-		attributes.put("icons", "font");
-		attributes.put("stylesheet", "css/spring.css");
-		asciidoctorTask.attributes(attributes);
+	private void configureAsciidoctorTask(Project project, AbstractAsciidoctorTask asciidoctorTask) {
+		asciidoctorTask.configurations(EXTENSIONS_CONFIGURATION);
+		configureCommonAttributes(project, asciidoctorTask);
+		configureOptions(asciidoctorTask);
+		asciidoctorTask.baseDirFollowsSourceDir();
+		createSyncDocumentationSourceTask(project, asciidoctorTask);
+		if (asciidoctorTask instanceof AsciidoctorTask) {
+			configureAsciidoctorHtmlTask(project, (AsciidoctorTask) asciidoctorTask);
+		}
 	}
 
 	private void configureCommonAttributes(Project project, AbstractAsciidoctorTask asciidoctorTask) {
@@ -169,43 +128,23 @@ private String determineGitHubTag(Project project) {
 		return (version.endsWith("-SNAPSHOT")) ? "master" : version;
 	}
 
-	/**
-	 * {@link Task} for unzipping the documentation resources.
-	 */
-	public static class UnzipDocumentationResources extends DefaultTask {
-
-		private FileCollection resources;
-
-		private File outputDir;
-
-		@InputFiles
-		public FileCollection getResources() {
-			return this.resources;
-		}
-
-		public void setResources(FileCollection resources) {
-			this.resources = resources;
-		}
-
-		@OutputDirectory
-		public File getOutputDir() {
-			return this.outputDir;
-		}
-
-		public void setOutputDir(File outputDir) {
-			this.outputDir = outputDir;
-		}
+	private void configureOptions(AbstractAsciidoctorTask asciidoctorTask) {
+		asciidoctorTask.options(Collections.singletonMap("doctype", "book"));
+	}
 
-		@TaskAction
-		void syncDocumentationResources() {
-			getProject().sync((copySpec) -> {
-				copySpec.into(this.outputDir);
-				for (File resource : this.resources) {
-					copySpec.from(getProject().zipTree(resource));
-				}
-			});
-		}
+	private Sync createSyncDocumentationSourceTask(Project project, AbstractAsciidoctorTask asciidoctorTask) {
+		Sync syncDocumentationSource = project.getTasks()
+				.create("syncDocumentationSourceFor" + StringUtils.capitalize(asciidoctorTask.getName()), Sync.class);
+		File syncedSource = new File(project.getBuildDir(), "docs/src/" + asciidoctorTask.getName());
+		syncDocumentationSource.setDestinationDir(syncedSource);
+		syncDocumentationSource.from("src/docs/");
+		asciidoctorTask.dependsOn(syncDocumentationSource);
+		asciidoctorTask.setSourceDir(project.relativePath(new File(syncedSource, "asciidoc/")));
+		return syncDocumentationSource;
+	}
 
+	private void configureAsciidoctorHtmlTask(Project project, AsciidoctorTask asciidoctorTask) {
+		asciidoctorTask.outputOptions((outputOptions) -> outputOptions.backends("spring-html"));
 	}
 
 }

buildSrc/src/main/java/org/springframework/boot/build/context/properties/ConfigurationTable.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2020 the original author or authors.
+ * Copyright 2012-2021 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.
@@ -46,7 +46,7 @@ void addEntry(ConfigurationTableEntry... entries) {
 
 	String toAsciidocTable() {
 		AsciidocBuilder builder = new AsciidocBuilder();
-		builder.appendln("[cols=\"2,1,1\", options=\"header\"]");
+		builder.appendln("[cols=\"4,3,3\", options=\"header\"]");
 		builder.appendln("|===");
 		builder.appendln("|Key|Default Value|Description");
 		builder.appendln();

buildSrc/src/test/java/org/springframework/boot/build/context/properties/ConfigurationTableTests.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2020 the original author or authors.
+ * Copyright 2012-2021 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.
@@ -38,7 +38,7 @@ void simpleTable() {
 				"This is another description.", false);
 		table.addEntry(new SingleConfigurationTableEntry(first));
 		table.addEntry(new SingleConfigurationTableEntry(second));
-		assertThat(table.toAsciidocTable()).isEqualTo("[cols=\"2,1,1\", options=\"header\"]" + NEWLINE + "|==="
+		assertThat(table.toAsciidocTable()).isEqualTo("[cols=\"4,3,3\", options=\"header\"]" + NEWLINE + "|==="
 				+ NEWLINE + "|Key|Default Value|Description" + NEWLINE + NEWLINE
 				+ "|[[spring.test.other]]<<spring.test.other,`+spring.test.other+`>>" + NEWLINE + "|`+other value+`"
 				+ NEWLINE + "|+++This is another description.+++" + NEWLINE + NEWLINE

spring-boot-project/spring-boot-actuator-autoconfigure/build.gradle

@@ -11,9 +11,6 @@ plugins {
 description = "Spring Boot Actuator AutoConfigure"
 
 configurations {
-	asciidoctorExtensions {
-		extendsFrom dependencyManagement
-	}
 	documentation
 }
 
@@ -170,14 +167,12 @@ tasks.withType(org.asciidoctor.gradle.jvm.AbstractAsciidoctorTask) {
 }
 
 asciidoctor {
-	configurations "asciidoctorExtensions"
 	sources {
 		include "index.adoc"
 	}
 }
 
 asciidoctorPdf {
-	configurations "asciidoctorExtensions"
 	sources {
 		include "index.adoc"
 	}

spring-boot-project/spring-boot-docs/build.gradle

@@ -10,9 +10,6 @@ description = "Spring Boot Docs"
 
 configurations {
 	actuatorApiDocumentation
-	asciidoctorExtensions {
-		extendsFrom dependencyManagement
-	}
 	autoConfiguration
 	configurationProperties
 	gradlePluginDocumentation
@@ -46,7 +43,6 @@ plugins.withType(EclipsePlugin) {
 dependencies {
 	actuatorApiDocumentation(project(path: ":spring-boot-project:spring-boot-actuator-autoconfigure", configuration: "documentation"))
 
-	asciidoctorExtensions("io.spring.asciidoctor:spring-asciidoctor-extensions-block-switch")
 	asciidoctorExtensions("io.spring.asciidoctor:spring-asciidoctor-extensions-spring-boot")
 	asciidoctorExtensions(project(path: ":spring-boot-project:spring-boot-actuator-autoconfigure"))
 	asciidoctorExtensions(project(path: ":spring-boot-project:spring-boot-autoconfigure"))
@@ -192,7 +188,6 @@ task documentConfigurationProperties(type: org.springframework.boot.build.contex
 
 tasks.withType(org.asciidoctor.gradle.jvm.AbstractAsciidoctorTask) {
 	dependsOn dependencyVersions
-	configurations "asciidoctorExtensions"
 	baseDirFollowsSourceDir()
 	asciidoctorj {
 		fatalWarnings = ['^((?!successfully validated).)*$']

spring-boot-project/spring-boot-parent/build.gradle

@@ -151,7 +151,6 @@ bom {
 	library("Spring Asciidoctor Extensions", "0.5.0") {
 		group("io.spring.asciidoctor") {
 			modules = [
-				"spring-asciidoctor-extensions-block-switch",
 				"spring-asciidoctor-extensions-spring-boot"
 			]
 		}

spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/build.gradle

@@ -15,9 +15,6 @@ toolchain {
 }
 
 configurations {
-	asciidoctorExtensions {
-		extendsFrom dependencyManagement
-	}
 	documentation
 }
 
@@ -31,8 +28,6 @@ repositories {
 }
 
 dependencies {
-	asciidoctorExtensions("io.spring.asciidoctor:spring-asciidoctor-extensions-block-switch")
-
 	implementation(project(":spring-boot-project:spring-boot-tools:spring-boot-buildpack-platform"))
 	implementation(project(":spring-boot-project:spring-boot-tools:spring-boot-loader-tools"))
 	implementation("io.spring.gradle:dependency-management-plugin")
@@ -85,7 +80,6 @@ tasks.withType(org.asciidoctor.gradle.jvm.AbstractAsciidoctorTask) {
 }
 
 asciidoctor {
-	configurations "asciidoctorExtensions"
 	sources {
 		include "index.adoc"
 	}