Bundle Javadoc with Antora

- Remove javadoc related tasks from root project - Add aggregated javadoc task to spring-shell-docs - Various antora version updates - Bundle javadoc via collector into antora build - Remove refs to distZip in workflows - Relates #1132
spring-projects · Aug 29, 2024 · 6983ef5 · 6983ef5
1 parent 208e41b
commit 6983ef5
Show file tree

Hide file tree

Showing 11 changed files with 66 additions and 258 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -68,5 +68,5 @@ jobs:
           GRADLE_ENTERPRISE_CACHE_PASSWORD: ${{ secrets.GRADLE_ENTERPRISE_CACHE_PASSWORD }}
           GRADLE_ENTERPRISE_ACCESS_KEY: ${{ secrets.GRADLE_ENTERPRISE_SECRET_ACCESS_KEY }}
         run: |
-          jf rt gradle build distZip artifactoryPublish
+          jf rt gradle build artifactoryPublish
           jf rt build-publish
diff --git a/.github/workflows/release-ga.yml b/.github/workflows/release-ga.yml
@@ -59,7 +59,7 @@ jobs:
         GRADLE_ENTERPRISE_CACHE_PASSWORD: ${{ secrets.GRADLE_ENTERPRISE_CACHE_PASSWORD }}
         GRADLE_ENTERPRISE_ACCESS_KEY: ${{ secrets.GRADLE_ENTERPRISE_SECRET_ACCESS_KEY }}
       run: |
-        jf rt gradle build distZip artifactoryPublish
+        jf rt gradle build artifactoryPublish
         jf rt build-publish
     - name: Push Release
       env:

diff --git a/.github/workflows/release-milestone.yml b/.github/workflows/release-milestone.yml
@@ -63,7 +63,7 @@ jobs:
         GRADLE_ENTERPRISE_CACHE_PASSWORD: ${{ secrets.GRADLE_ENTERPRISE_CACHE_PASSWORD }}
         GRADLE_ENTERPRISE_ACCESS_KEY: ${{ secrets.GRADLE_ENTERPRISE_SECRET_ACCESS_KEY }}
       run: |
-        jf rt gradle build distZip artifactoryPublish
+        jf rt gradle build artifactoryPublish
         jf rt build-publish
     - name: Push Release
       env:

diff --git a/build.gradle b/build.gradle
@@ -1,6 +1,5 @@
 plugins {
 	id "base"
-	id 'org.springframework.shell.root'
 }
 
 description = 'Spring Shell'

diff --git a/buildSrc/build.gradle b/buildSrc/build.gradle
@@ -26,7 +26,6 @@ dependencies {
 	implementation(platform("org.springframework.boot:spring-boot-dependencies:${springBootVersion}"))
 	implementation "org.springframework.boot:spring-boot-gradle-plugin:${springBootVersion}"
 	implementation("org.springframework:spring-core")
-	implementation 'org.asciidoctor:asciidoctor-gradle-jvm:3.3.2'
 	implementation 'org.jfrog.buildinfo:build-info-extractor-gradle:4.29.0'
 	implementation "org.graalvm.buildtools:native-gradle-plugin:${nativeBuildToolsVersion}"
 }
@@ -49,10 +48,6 @@ gradlePlugin {
 			id = "org.springframework.shell.docs"
 			implementationClass = "org.springframework.shell.gradle.DocsPlugin"
 		}
-		distPlugin {
-			id = "org.springframework.shell.root"
-			implementationClass = "org.springframework.shell.gradle.RootPlugin"
-		}
 		samplePlugin {
 			id = "org.springframework.shell.sample"
 			implementationClass = "org.springframework.shell.gradle.SamplePlugin"

diff --git a/buildSrc/src/main/java/org/springframework/shell/gradle/DocsPlugin.java b/buildSrc/src/main/java/org/springframework/shell/gradle/DocsPlugin.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2022-2023 the original author or authors.
+ * Copyright 2022-2024 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.
@@ -16,166 +16,67 @@
 package org.springframework.shell.gradle;
 
 import java.io.File;
-import java.time.LocalDate;
-import java.util.Collections;
-import java.util.HashMap;
-import java.util.Map;
 
-import org.asciidoctor.gradle.base.AsciidoctorAttributeProvider;
-import org.asciidoctor.gradle.jvm.AbstractAsciidoctorTask;
-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.Plugin;
 import org.gradle.api.Project;
-import org.gradle.api.Task;
 import org.gradle.api.plugins.JavaLibraryPlugin;
 import org.gradle.api.plugins.JavaPlugin;
+import org.gradle.api.plugins.JavaPluginConvention;
 import org.gradle.api.plugins.PluginManager;
 import org.gradle.api.publish.tasks.GenerateModuleMetadata;
-import org.gradle.api.tasks.PathSensitivity;
-import org.gradle.api.tasks.Sync;
-import org.springframework.util.StringUtils;
+import org.gradle.api.tasks.SourceSet;
+import org.gradle.api.tasks.javadoc.Javadoc;
+import org.gradle.external.javadoc.CoreJavadocOptions;
+import org.gradle.external.javadoc.JavadocMemberLevel;
+import org.gradle.external.javadoc.JavadocOutputLevel;
 
 /**
  * @author Janne Valkealahti
  */
 class DocsPlugin implements Plugin<Project> {
 
-	private static final String ASCIIDOCTORJ_VERSION = "2.4.3";
-	private static final String EXTENSIONS_CONFIGURATION_NAME = "asciidoctorExtensions";
-
 	@Override
 	public void apply(Project project) {
 		PluginManager pluginManager = project.getPluginManager();
 		pluginManager.apply(JavaPlugin.class);
 		pluginManager.apply(JavaLibraryPlugin.class);
 		pluginManager.apply(ManagementConfigurationPlugin.class);
 		pluginManager.apply(SpringMavenPlugin.class);
-		pluginManager.apply(AsciidoctorJPlugin.class);
 
-		ExtractVersionConstraints dependencyVersions = project.getTasks().create("dependencyVersions",
-			ExtractVersionConstraints.class, task -> {
-				task.enforcedPlatform(":spring-shell-management");
-			});
+		createApiTask(project);
 
-		project.getPlugins().withType(AsciidoctorJPlugin.class, (asciidoctorPlugin) -> {
-			// makeAllWarningsFatal(project);
-			upgradeAsciidoctorJVersion(project);
-			createAsciidoctorExtensionsConfiguration(project);
-			project.getTasks()
-				.withType(AbstractAsciidoctorTask.class,
-						(asciidoctorTask) -> configureAsciidoctorTask(project, asciidoctorTask, dependencyVersions));
-		});
 		project.getTasks().withType(GenerateModuleMetadata.class, metadata -> {
 			metadata.setEnabled(false);
 		});
 	}
 
-	private void upgradeAsciidoctorJVersion(Project project) {
-		project.getExtensions().getByType(AsciidoctorJExtension.class).setVersion(ASCIIDOCTORJ_VERSION);
-	}
-
-	private void createAsciidoctorExtensionsConfiguration(Project project) {
-		project.getConfigurations().create(EXTENSIONS_CONFIGURATION_NAME, (configuration) -> {
-			configuration.getDependencies()
-				.add(project.getDependencies()
-					.create("io.spring.asciidoctor.backends:spring-asciidoctor-backends:0.0.5"));
+	private Javadoc createApiTask(Project project) {
+		Javadoc api = project.getTasks().create("aggregatedJavadoc", Javadoc.class, a -> {
+			a.setGroup("Documentation");
+			a.setDescription("Generates aggregated Javadoc API documentation.");
+			a.setDestinationDir(new File(project.getBuildDir(), "generated-antora-javadocs/modules/ROOT/assets/attachments/api/java"));
+			a.setTitle(String.format("Spring Shell %s API", project.getVersion()));
+			CoreJavadocOptions options = (CoreJavadocOptions) a.getOptions();
+			options.windowTitle(String.format("Spring Shell %s API", project.getVersion()));
+			options.setMemberLevel(JavadocMemberLevel.PROTECTED);
+			options.setOutputLevel(JavadocOutputLevel.QUIET);
+			options.addStringOption("Xdoclint:none", "-quiet");
 		});
-	}
 
-	private void configureAsciidoctorTask(Project project, AbstractAsciidoctorTask asciidoctorTask, ExtractVersionConstraints dependencyVersions) {
-		asciidoctorTask.configurations(EXTENSIONS_CONFIGURATION_NAME);
-		configureCommonAttributes(project, asciidoctorTask, dependencyVersions);
-		configureOptions(asciidoctorTask);
-		asciidoctorTask.baseDirFollowsSourceDir();
-		createSyncDocumentationSourceTask(project, asciidoctorTask, dependencyVersions);
-		if (asciidoctorTask instanceof AsciidoctorTask task) {
-			task.outputOptions((outputOptions) -> outputOptions.backends("spring-html"));
-		}
-	}
-
-	private void configureOptions(AbstractAsciidoctorTask asciidoctorTask) {
-		asciidoctorTask.options(Collections.singletonMap("doctype", "book"));
-	}
+		project.getRootProject().getSubprojects().forEach(p -> {
+			p.getPlugins().withType(ModulePlugin.class, m -> {
+				JavaPluginConvention java = p.getConvention().getPlugin(JavaPluginConvention.class);
+				SourceSet mainSourceSet = java.getSourceSets().getByName("main");
 
-	private Sync createSyncDocumentationSourceTask(Project project, AbstractAsciidoctorTask asciidoctorTask, ExtractVersionConstraints dependencyVersions) {
-		Sync syncDocumentationSource = project.getTasks()
-			.create("syncDocumentationSourceFor" + StringUtils.capitalize(asciidoctorTask.getName()), Sync.class);
-		syncDocumentationSource.preserve(filter -> {
-			filter.include("**/*");
-		});
-		File syncedSource = new File(project.getBuildDir(), "docs/src/" + asciidoctorTask.getName());
-		syncDocumentationSource.setDestinationDir(syncedSource);
-		syncDocumentationSource.from("src/main/");
-		asciidoctorTask.dependsOn(syncDocumentationSource);
-		asciidoctorTask.dependsOn(dependencyVersions);
-		Sync snippetsResources = createSnippetsResourcesTask(project);
-		asciidoctorTask.dependsOn(snippetsResources);
-		asciidoctorTask.getInputs()
-			.dir(syncedSource)
-			.withPathSensitivity(PathSensitivity.RELATIVE)
-			.withPropertyName("synced source");
-		asciidoctorTask.setSourceDir(project.relativePath(new File(syncedSource, "asciidoc/")));
-		return syncDocumentationSource;
-	}
+				api.setSource(api.getSource().plus(mainSourceSet.getAllJava()));
 
-	private Sync createSnippetsResourcesTask(Project project) {
-		Sync sync = project.getTasks().create("snippetResources", Sync.class, s -> {
-			s.from(new File(project.getRootProject().getRootDir(), "spring-shell-docs/src/test/java/org/springframework/shell"), spec -> {
-				spec.include("docs/*");
-			});
-			s.preserve(filter -> {
-				filter.include("**/*");
-			});
-			File destination = new File(project.getBuildDir(), "docs/src/asciidoctor/asciidoc");
-			s.into(destination);
-		});
-		return sync;
-	}
-
-	private void configureCommonAttributes(Project project, AbstractAsciidoctorTask asciidoctorTask,
-			ExtractVersionConstraints dependencyVersions) {
-		asciidoctorTask.doFirst(new Action<Task>() {
-
-			@Override
-			public void execute(Task arg0) {
-				asciidoctorTask.getAttributeProviders().add(new AsciidoctorAttributeProvider() {
-					@Override
-					public Map<String, Object> getAttributes() {
-						Map<String, String> versionConstraints = dependencyVersions.getVersionConstraints();
-						Map<String, Object> attrs = new HashMap<>();
-						attrs.put("spring-version", versionConstraints.get("org.springframework:spring-core"));
-						attrs.put("spring-boot-version", versionConstraints.get("org.springframework.boot:spring-boot"));
-						return attrs;
-					}
+				p.getTasks().withType(Javadoc.class, j -> {
+					api.setClasspath(api.getClasspath().plus(j.getClasspath()));
 				});
-			}
+			});
 		});
 
-		Map<String, Object> attributes = new HashMap<>();
-		attributes.put("toc", "left");
-		attributes.put("icons", "font");
-		attributes.put("idprefix", "");
-		attributes.put("idseparator", "-");
-		attributes.put("docinfo", "shared");
-		attributes.put("sectanchors", "");
-		attributes.put("sectnums", "");
-		attributes.put("today-year", LocalDate.now().getYear());
-		attributes.put("snippets", "docs");
-
-		asciidoctorTask.getAttributeProviders().add(new AsciidoctorAttributeProvider() {
-			@Override
-			public Map<String, Object> getAttributes() {
-				Object version = project.getVersion();
-				Map<String, Object> attrs = new HashMap<>();
-				if (version != null && version.toString() != Project.DEFAULT_VERSION) {
-					attrs.put("project-version", version);
-				}
-				return attrs;
-			}
-		});
-		asciidoctorTask.attributes(attributes);
+		return api;
 	}
+
 }
diff --git a/buildSrc/src/main/java/org/springframework/shell/gradle/RootPlugin.java b/buildSrc/src/main/java/org/springframework/shell/gradle/RootPlugin.java
diff --git a/spring-shell-docs/antora-playbook.yml b/spring-shell-docs/antora-playbook.yml
@@ -3,12 +3,7 @@
 # The purpose of this Antora playbook is to build the docs in the current branch.
 antora:
   extensions:
-    - '@springio/antora-extensions/partial-build-extension'
-    - require: '@springio/antora-extensions/latest-version-extension'
-    - require: '@springio/antora-extensions/inject-collector-cache-config-extension'
-    - '@antora/collector-extension'
-    - '@antora/atlas-extension'
-    - require: '@springio/antora-extensions/root-component-extension'
+    - require: '@springio/antora-extensions'
       root_component_name: 'shell'
     - require: '@springio/antora-extensions/asciinema-extension'
 site:
@@ -30,6 +25,7 @@ asciidoc:
   extensions:
     - '@asciidoctor/tabs'
     - '@springio/asciidoctor-extensions'
+    - '@springio/asciidoctor-extensions/javadoc-extension'
   sourcemap: true
 urls:
   latest_version_segment: ''

diff --git a/spring-shell-docs/antora.yml b/spring-shell-docs/antora.yml
@@ -5,11 +5,16 @@ nav:
   - modules/ROOT/nav.adoc
 ext:
   collector:
-    run:
-      command: gradlew -q "-Dorg.gradle.jvmargs=-Xmx3g -XX:+HeapDumpOnOutOfMemoryError" :spring-shell-docs:generateAntoraYml
-      local: true
-    scan:
-      dir: ./build/generated-antora-resources
+    - run:
+        command: gradlew -q "-Dorg.gradle.jvmargs=-Xmx3g -XX:+HeapDumpOnOutOfMemoryError" :spring-shell-docs:generateAntoraYml
+        local: true
+      scan:
+        dir: ./build/generated-antora-resources
+    - run:
+        command: gradlew -q "-Dorg.gradle.jvmargs=-Xmx3g -XX:+HeapDumpOnOutOfMemoryError" :spring-shell-docs:aggregatedJavadoc
+        local: true
+      scan:
+        dir: ./build/generated-antora-javadocs
 
 asciidoc:
   attributes: