Skip to content

Commit c93ae25

Browse files
bclozelbclozel
committed
Stop publishing distribution zip artifact
Prior to this commit, the Spring Framework build would publish several zip artifacts: * a "*-schema.zip" containing all the XSD schemas produced * a "*-docs.zip" containing the API docs * a "*-dist.zip" containing all of the above, plus module jars Since the reference docs are now produced by Antora in a separate process, the "*-docs.zip" does not contain the reference docs anymore. But it still contains the API docs which are automatically fetched from the artifact repository and published on the docs.spring.io website. This commit intends to update the current arrangement and optimize the build. First, the "*-dist.zip" is not published anymore, since it cannot be consumed anyway by the community: repo.spring.io does not distribute release artifacts publicly, developers are expected to get them from Maven Central. This arrangement is quite dated anyway and is not really useful in current application build setups. The generation of API docs is moved to a new "framework-api" module, separating it from the reference docs module ("framework-docs") which contains Java, Kotlin and Asciidoctor sources. This removes the custom javadoc aggregation task and instead uses a dedicated Gradle plugin. This change also adds a new `-PskipDocs` Gradle project property that skips entirely the documentation tasks (javadoc, kdocs) as well as the "distrbution" tasks managed in the framework-api module. This allows developers to publish locally a SNAPSHOT of Spring Framework without creating the entire documentation distribution. This is particularly useful for local testing. For example, `$ ./gradlew pTML -PskipDocs`. Closes spring-projectsgh-31049
1 parent 9133e61 commit c93ae25

File tree

8 files changed

+191
-169
lines changed

8 files changed

+191
-169
lines changed

‎.gitignore

+1-2
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,7 @@ derby.log
2121
/build
2222
buildSrc/build
2323
/spring-*/build
24-
/framework-bom/build
25-
/framework-docs/build
24+
/framework-*/build
2625
/integration-tests/build
2726
/src/asciidoc/build
2827
spring-test/test-output/

‎build.gradle

+3-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
plugins {
2-
id 'io.freefair.aspectj' version '8.0.1' apply false
2+
id 'io.freefair.aspectj' version '8.2.2' apply false
33
// kotlinVersion is managed in gradle.properties
44
id 'org.jetbrains.kotlin.plugin.serialization' version "${kotlinVersion}" apply false
55
id 'org.jetbrains.dokka' version '1.8.20'
@@ -13,10 +13,11 @@ plugins {
1313

1414
ext {
1515
moduleProjects = subprojects.findAll { it.name.startsWith("spring-") }
16-
javaProjects = subprojects - project(":framework-bom") - project(":framework-platform")
16+
javaProjects = subprojects.findAll { !it.name.startsWith("framework-") }
1717
}
1818

1919
configure(allprojects) { project ->
20+
apply plugin: "org.springframework.build.localdev"
2021
repositories {
2122
mavenCentral()
2223
maven {

‎buildSrc/build.gradle

+4
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,10 @@ gradlePlugin {
3838
id = "org.springframework.build.conventions"
3939
implementationClass = "org.springframework.build.ConventionsPlugin"
4040
}
41+
localDevPlugin {
42+
id = "org.springframework.build.localdev"
43+
implementationClass = "org.springframework.build.dev.LocalDevelopmentPlugin"
44+
}
4145
optionalDependenciesPlugin {
4246
id = "org.springframework.build.optional-dependencies"
4347
implementationClass = "org.springframework.build.optional.OptionalDependenciesPlugin"

‎buildSrc/src/main/java/org/springframework/build/dev/LocalDevelopmentPlugin.java

+49
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
/*
2+
* Copyright 2002-2023 the original author or authors.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* https://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package org.springframework.build.dev;
18+
19+
import org.gradle.api.Plugin;
20+
import org.gradle.api.Project;
21+
import org.gradle.api.plugins.JavaBasePlugin;
22+
23+
/**
24+
* {@link Plugin} that skips documentation tasks when the {@code "-PskipDocs"} property is defined.
25+
*
26+
* @author Brian Clozel
27+
*/
28+
public class LocalDevelopmentPlugin implements Plugin<Project> {
29+
30+
private static final String SKIP_DOCS_PROPERTY = "skipDocs";
31+
32+
@Override
33+
public void apply(Project target) {
34+
if (target.hasProperty(SKIP_DOCS_PROPERTY)) {
35+
skipDocumentationTasks(target);
36+
target.subprojects(this::skipDocumentationTasks);
37+
}
38+
}
39+
40+
private void skipDocumentationTasks(Project project) {
41+
project.afterEvaluate(p -> {
42+
p.getTasks().matching(task -> {
43+
return JavaBasePlugin.DOCUMENTATION_GROUP.equals(task.getGroup())
44+
|| "distribution".equals(task.getGroup());
45+
})
46+
.forEach(task -> task.setEnabled(false));
47+
});
48+
}
49+
}

‎ci/pipeline.yml

+3-7
Original file line numberDiff line numberDiff line change
@@ -198,21 +198,17 @@ jobs:
198198
threads: 8
199199
artifact_set:
200200
- include:
201-
- "/**/framework-docs-*.zip"
201+
- "/**/framework-api-*.zip"
202202
properties:
203203
"zip.name": "spring-framework"
204204
"zip.displayname": "Spring Framework"
205205
"zip.deployed": "false"
206206
- include:
207-
- "/**/framework-docs-*-docs.zip"
207+
- "/**/framework-api-*-api.zip"
208208
properties:
209209
"zip.type": "docs"
210210
- include:
211-
- "/**/framework-docs-*-dist.zip"
212-
properties:
213-
"zip.type": "dist"
214-
- include:
215-
- "/**/framework-docs-*-schema.zip"
211+
- "/**/framework-api-*-schema.zip"
216212
properties:
217213
"zip.type": "schema"
218214
get_params:

‎framework-api/framework-api.gradle

+129
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
plugins {
2+
id 'java-platform'
3+
id 'io.freefair.aggregate-javadoc' version '8.2.2'
4+
}
5+
6+
description = "Spring Framework API Docs"
7+
8+
apply from: "${rootDir}/gradle/publications.gradle"
9+
10+
repositories {
11+
maven {
12+
url "https://repo.spring.io/release"
13+
}
14+
}
15+
16+
configurations {
17+
dependencyManagement {
18+
canBeConsumed = false
19+
canBeResolved = false
20+
visible = false
21+
}
22+
matching { it.name.endsWith("Classpath") }.all { it.extendsFrom(dependencyManagement) }
23+
}
24+
25+
26+
dependencies {
27+
dependencyManagement(enforcedPlatform(dependencies.project(path: ":framework-platform")))
28+
rootProject.subprojects.findAll { it.name.startsWith("spring-") }.each { moduleProject ->
29+
javadoc moduleProject
30+
}
31+
}
32+
33+
javadoc {
34+
title = "${rootProject.description} ${version} API"
35+
options {
36+
encoding = "UTF-8"
37+
memberLevel = JavadocMemberLevel.PROTECTED
38+
author = true
39+
header = rootProject.description
40+
use = true
41+
overview = "framework-docs/src/docs/api/overview.html"
42+
splitIndex = true
43+
links(rootProject.ext.javadocLinks)
44+
addBooleanOption('Xdoclint:syntax,reference', true) // only check syntax and reference with doclint
45+
addBooleanOption('Werror', true) // fail build on Javadoc warnings
46+
}
47+
maxMemory = "1024m"
48+
destinationDir = file("$buildDir/docs/javadoc")
49+
doFirst {
50+
classpath += files(
51+
// ensure the javadoc process can resolve types compiled from .aj sources
52+
project(":spring-aspects").sourceSets.main.output
53+
)
54+
}
55+
}
56+
57+
/**
58+
* Produce KDoc for all Spring Framework modules in "build/docs/kdoc"
59+
*/
60+
rootProject.tasks.dokkaHtmlMultiModule.configure {
61+
dependsOn {
62+
tasks.named("javadoc")
63+
}
64+
moduleName.set("spring-framework")
65+
outputDirectory.set(project.file("$buildDir/docs/kdoc"))
66+
}
67+
68+
/**
69+
* Zip all Java docs (javadoc & kdoc) into a single archive
70+
*/
71+
tasks.register('docsZip', Zip) {
72+
dependsOn = ['javadoc', rootProject.tasks.dokkaHtmlMultiModule]
73+
group = "distribution"
74+
description = "Builds -${archiveClassifier} archive containing api and reference " +
75+
"for deployment at https://docs.spring.io/spring-framework/docs/."
76+
77+
archiveBaseName.set("spring-framework")
78+
archiveClassifier.set("docs")
79+
from("src/dist") {
80+
include "changelog.txt"
81+
}
82+
from(javadoc) {
83+
into "javadoc-api"
84+
}
85+
from(rootProject.tasks.dokkaHtmlMultiModule.outputDirectory) {
86+
into "kdoc-api"
87+
}
88+
}
89+
90+
/**
91+
* Zip all Spring Framework schemas into a single archive
92+
*/
93+
tasks.register('schemaZip', Zip) {
94+
group = "distribution"
95+
archiveBaseName.set("spring-framework")
96+
archiveClassifier.set("schema")
97+
description = "Builds -${archiveClassifier} archive containing all " +
98+
"XSDs for deployment at https://springframework.org/schema."
99+
duplicatesStrategy DuplicatesStrategy.EXCLUDE
100+
moduleProjects.each { module ->
101+
def Properties schemas = new Properties();
102+
103+
module.sourceSets.main.resources.find {
104+
(it.path.endsWith("META-INF/spring.schemas") || it.path.endsWith("META-INF\\spring.schemas"))
105+
}?.withInputStream { schemas.load(it) }
106+
107+
for (def key : schemas.keySet()) {
108+
def shortName = key.replaceAll(/http.*schema.(.*).spring-.*/, '$1')
109+
assert shortName != key
110+
File xsdFile = module.sourceSets.main.resources.find {
111+
(it.path.endsWith(schemas.get(key)) || it.path.endsWith(schemas.get(key).replaceAll('\\/', '\\\\')))
112+
}
113+
assert xsdFile != null
114+
into(shortName) {
115+
from xsdFile.path
116+
}
117+
}
118+
}
119+
}
120+
121+
publishing {
122+
group "distribution"
123+
publications {
124+
mavenJava(MavenPublication) {
125+
artifact docsZip
126+
artifact schemaZip
127+
}
128+
}
129+
}

0 commit comments

Comments
 (0)