Spring/spring-shell
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Bundle Javadoc with Antora

Browse Source 
- 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
This commit is contained in:
Janne Valkealahti
2024-08-29 08:39:56 +01:00
parent 208e41ba7b
commit 6983ef5c10
11 changed files with 66 additions and 258 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.github/workflows/ci.yml vendored
View File

@@ -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

2
.github/workflows/release-ga.yml vendored
View File

@@ -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:

2
.github/workflows/release-milestone.yml vendored
View File

@@ -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:

1
build.gradle
View File

@@ -1,6 +1,5 @@
plugins {
id "base"
id 'org.springframework.shell.root'
}
description = 'Spring Shell'

5
buildSrc/build.gradle
View File

@@ -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"

157
buildSrc/src/main/java/org/springframework/shell/gradle/DocsPlugin.java
View File

@@ -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<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();
@@ -53,129 +42,41 @@ class DocsPlugin implements Plugin<Project> {
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<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;
}
}

102
buildSrc/src/main/java/org/springframework/shell/gradle/RootPlugin.java
View File

@@ -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<Project> {
@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;
}
}

8
spring-shell-docs/antora-playbook.yml
View File

@@ -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: ''

15
spring-shell-docs/antora.yml
View File

@@ -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:

3
spring-shell-docs/modules/ROOT/nav.adoc
View File

@@ -96,4 +96,5 @@
** xref:appendices/debugging/index.adoc[]
** xref:appendices/tui/index.adoc[]
*** xref:appendices/tui/viewdev.adoc[]
*** xref:appendices/tui/catalog.adoc[]
*** xref:appendices/tui/catalog.adoc[]
* xref:attachment$api/java/index.html[Javadoc,role=link-external,window=_blank]

27
spring-shell-docs/spring-shell-docs.gradle
View File

@@ -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'
]
}