From 6983ef5c103d506034dab6d360f258c23c844ace Mon Sep 17 00:00:00 2001 From: Janne Valkealahti Date: Thu, 29 Aug 2024 08:39:56 +0100 Subject: [PATCH] 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 --- .github/workflows/ci.yml | 2 +- .github/workflows/release-ga.yml | 2 +- .github/workflows/release-milestone.yml | 2 +- build.gradle | 1 - buildSrc/build.gradle | 5 - .../shell/gradle/DocsPlugin.java | 157 ++++-------------- .../shell/gradle/RootPlugin.java | 102 ------------ spring-shell-docs/antora-playbook.yml | 8 +- spring-shell-docs/antora.yml | 15 +- spring-shell-docs/modules/ROOT/nav.adoc | 3 +- spring-shell-docs/spring-shell-docs.gradle | 27 ++- 11 files changed, 66 insertions(+), 258 deletions(-) delete mode 100644 buildSrc/src/main/java/org/springframework/shell/gradle/RootPlugin.java diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 503985e8..0e6229a1 100644 --- 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 index 35c86858..e2fc555d 100644 --- 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 index a8dd1d08..198c19dd 100644 --- 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 index 0294e4c8..485d2ac4 100644 --- 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 index f02991c6..ed6b6d67 100644 --- 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 index 8ce5d3b7..3a35cf4c 100644 --- 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,36 +16,25 @@ 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 { - 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(); @@ -53,129 +42,41 @@ class DocsPlugin implements Plugin { 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")); - } - } + 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 void configureOptions(AbstractAsciidoctorTask asciidoctorTask) { - asciidoctorTask.options(Collections.singletonMap("doctype", "book")); - } + api.setSource(api.getSource().plus(mainSourceSet.getAllJava())); - 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; - } - - 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() { - - @Override - public void execute(Task arg0) { - asciidoctorTask.getAttributeProviders().add(new AsciidoctorAttributeProvider() { - @Override - public Map getAttributes() { - Map versionConstraints = dependencyVersions.getVersionConstraints(); - Map 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 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 getAttributes() { - Object version = project.getVersion(); - Map 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 deleted file mode 100644 index b64bc055..00000000 --- a/buildSrc/src/main/java/org/springframework/shell/gradle/RootPlugin.java +++ /dev/null @@ -1,102 +0,0 @@ -/* - * Copyright 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 - * - * https://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. - */ -package org.springframework.shell.gradle; - -import java.io.File; - -import org.asciidoctor.gradle.jvm.AsciidoctorJPlugin; -import org.gradle.api.Plugin; -import org.gradle.api.Project; -import org.gradle.api.plugins.JavaPluginConvention; -import org.gradle.api.plugins.PluginManager; -import org.gradle.api.publish.maven.plugins.MavenPublishPlugin; -import org.gradle.api.tasks.SourceSet; -import org.gradle.api.tasks.bundling.Zip; -import org.gradle.api.tasks.javadoc.Javadoc; -import org.gradle.external.javadoc.CoreJavadocOptions; - -/** - * Manages tasks creating zip file for docs and publishing it. - * - * @author Janne Valkealahti - */ -class RootPlugin implements Plugin { - - @Override - public void apply(Project project) { - PluginManager pluginManager = project.getPluginManager(); - pluginManager.apply(MavenPublishPlugin.class); - pluginManager.apply(PublishLocalPlugin.class); - // docsarchive needs to be created before artifactory - // conventions are used - project.getConfigurations().create("docsarchive"); - new ArtifactoryConventions().apply(project); - Javadoc apiTask = createApiTask(project); - Zip zipTask = createZipTask(project); - zipTask.dependsOn(apiTask); - } - - private Zip createZipTask(Project project) { - Zip zipTask = project.getTasks().create("distZip", Zip.class, zip -> { - zip.setGroup("Distribution"); - zip.from("spring-shell-docs/build/docs/asciidoc", copy -> { - copy.into("docs"); - }); - zip.from("build/api", copy -> { - copy.into("api"); - }); - }); - - project.getRootProject().getAllprojects().forEach(p -> { - p.getPlugins().withType(AsciidoctorJPlugin.class, a -> { - p.getTasksByName("asciidoctor", false).forEach(t -> { - zipTask.dependsOn(t); - });; - }); - }); - - // since gradle 8.3 archives configuration started to fail - // so using custom configuration name - project.getArtifacts().add("docsarchive", zipTask); - return zipTask; - } - - private Javadoc createApiTask(Project project) { - Javadoc api = project.getTasks().create("api", Javadoc.class, a -> { - a.setGroup("Documentation"); - a.setDescription("Generates aggregated Javadoc API documentation."); - a.setDestinationDir(new File(project.getBuildDir(), "api")); - CoreJavadocOptions options = (CoreJavadocOptions) a.getOptions(); - options.source("17"); - options.encoding("UTF-8"); - options.addStringOption("Xdoclint:none", "-quiet"); - }); - - project.getRootProject().getSubprojects().forEach(p -> { - p.getPlugins().withType(ModulePlugin.class, m -> { - JavaPluginConvention java = p.getConvention().getPlugin(JavaPluginConvention.class); - SourceSet mainSourceSet = java.getSourceSets().getByName("main"); - - api.setSource(api.getSource().plus(mainSourceSet.getAllJava())); - - p.getTasks().withType(Javadoc.class, j -> { - api.setClasspath(api.getClasspath().plus(j.getClasspath())); - }); - }); - }); - return api; - } -} diff --git a/spring-shell-docs/antora-playbook.yml b/spring-shell-docs/antora-playbook.yml index 60fc812f..4d36386a 100644 --- 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 index 9b34c10b..100c1d96 100644 --- 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: diff --git a/spring-shell-docs/modules/ROOT/nav.adoc b/spring-shell-docs/modules/ROOT/nav.adoc index a927b76e..154678c7 100644 --- a/spring-shell-docs/modules/ROOT/nav.adoc +++ b/spring-shell-docs/modules/ROOT/nav.adoc @@ -96,4 +96,5 @@ ** xref:appendices/debugging/index.adoc[] ** xref:appendices/tui/index.adoc[] *** xref:appendices/tui/viewdev.adoc[] -*** xref:appendices/tui/catalog.adoc[] \ No newline at end of file +*** xref:appendices/tui/catalog.adoc[] +* xref:attachment$api/java/index.html[Javadoc,role=link-external,window=_blank] diff --git a/spring-shell-docs/spring-shell-docs.gradle b/spring-shell-docs/spring-shell-docs.gradle index 036b0ec0..defab9c8 100644 --- a/spring-shell-docs/spring-shell-docs.gradle +++ b/spring-shell-docs/spring-shell-docs.gradle @@ -15,22 +15,35 @@ dependencies { testImplementation 'org.awaitility:awaitility' } -node { - version = '16.15.0' +jar { + enabled = false +} + +javadoc { + enabled = false +} + +javadocJar { + enabled = false +} + +sourcesJar { + enabled = false } antora { - version = '3.2.0-alpha.2' + version = '3.2.0-alpha.6' if (project.hasProperty('antoraLocalBarePlaybook') && antoraLocalBarePlaybook.toBoolean()) { playbook = 'local-bare-antora-playbook.yml' } options = [clean: true, fetch: !project.gradle.startParameter.offline, stacktrace: true] dependencies = [ '@antora/atlas-extension': '1.0.0-alpha.1', - '@antora/collector-extension': '1.0.0-alpha.3', - '@asciidoctor/tabs': '1.0.0-beta.3', - '@springio/antora-extensions': '1.8.1', - '@springio/asciidoctor-extensions': '1.0.0-alpha.8', + '@antora/collector-extension': '1.0.0-alpha.7', + '@asciidoctor/tabs': '1.0.0-beta.6', + '@springio/antora-extensions': '1.14.2', + '@springio/asciidoctor-extensions': '1.0.0-alpha.12', + 'asciinema-player': '3.7.1' ] }