Skip to content

Commit 68baa6e

Browse files
wilkinsonawilkinsona
committed
Make section IDs consistent in Maven Plugin docs and enforce it
Closes gh-26619
1 parent 032d92a commit 68baa6e

File tree

5 files changed

+173
-10
lines changed

5 files changed

+173
-10
lines changed

Diff for: ‎buildSrc/src/main/java/org/springframework/boot/build/mavenplugin/DocumentPluginGoals.java

+43-8
Original file line numberDiff line numberDiff line change
@@ -21,10 +21,12 @@
2121
import java.io.IOException;
2222
import java.io.PrintWriter;
2323
import java.util.List;
24+
import java.util.Map;
2425
import java.util.stream.Collectors;
2526

2627
import org.gradle.api.DefaultTask;
2728
import org.gradle.api.Task;
29+
import org.gradle.api.tasks.Input;
2830
import org.gradle.api.tasks.InputFile;
2931
import org.gradle.api.tasks.OutputDirectory;
3032
import org.gradle.api.tasks.TaskAction;
@@ -46,6 +48,8 @@ public class DocumentPluginGoals extends DefaultTask {
4648

4749
private File outputDir;
4850

51+
private Map<String, String> goalSections;
52+
4953
@OutputDirectory
5054
public File getOutputDir() {
5155
return this.outputDir;
@@ -55,6 +59,15 @@ public void setOutputDir(File outputDir) {
5559
this.outputDir = outputDir;
5660
}
5761

62+
@Input
63+
public Map<String, String> getGoalSections() {
64+
return this.goalSections;
65+
}
66+
67+
public void setGoalSections(Map<String, String> goalSections) {
68+
this.goalSections = goalSections;
69+
}
70+
5871
@InputFile
5972
public File getPluginXml() {
6073
return this.pluginXml;
@@ -80,7 +93,7 @@ private void writeOverview(Plugin plugin) throws IOException {
8093
writer.println("| Goal | Description");
8194
writer.println();
8295
for (Mojo mojo : plugin.getMojos()) {
83-
writer.printf("| <<goals-%s,%s:%s>>%n", mojo.getGoal(), plugin.getGoalPrefix(), mojo.getGoal());
96+
writer.printf("| <<%s,%s:%s>>%n", goalSectionId(mojo), plugin.getGoalPrefix(), mojo.getGoal());
8497
writer.printf("| %s%n", mojo.getDescription());
8598
writer.println();
8699
}
@@ -90,7 +103,7 @@ private void writeOverview(Plugin plugin) throws IOException {
90103

91104
private void documentMojo(Plugin plugin, Mojo mojo) throws IOException {
92105
try (PrintWriter writer = new PrintWriter(new FileWriter(new File(this.outputDir, mojo.getGoal() + ".adoc")))) {
93-
String sectionId = "goals-" + mojo.getGoal();
106+
String sectionId = goalSectionId(mojo);
94107
writer.println();
95108
writer.println();
96109
writer.printf("[[%s]]%n", sectionId);
@@ -105,12 +118,11 @@ private void documentMojo(Plugin plugin, Mojo mojo) throws IOException {
105118
List<Parameter> requiredParameters = parameters.stream()
106119
.filter(Parameter::isRequired)
107120
.collect(Collectors.toList());
108-
String parametersSectionId = sectionId + "-parameters";
109-
String detailsSectionId = parametersSectionId + "-details";
121+
String detailsSectionId = sectionId + ".parameter-details";
110122
if (!requiredParameters.isEmpty()) {
111123
writer.println();
112124
writer.println();
113-
writer.printf("[[%s-required]]%n", parametersSectionId);
125+
writer.printf("[[%s.required-parameters]]%n", sectionId);
114126
writer.println("== Required parameters");
115127
writeParametersTable(writer, detailsSectionId, requiredParameters);
116128
}
@@ -120,7 +132,7 @@ private void documentMojo(Plugin plugin, Mojo mojo) throws IOException {
120132
if (!optionalParameters.isEmpty()) {
121133
writer.println();
122134
writer.println();
123-
writer.printf("[[%s-optional]]%n", parametersSectionId);
135+
writer.printf("[[%s.optional-parameters]]%n", sectionId);
124136
writer.println("== Optional parameters");
125137
writeParametersTable(writer, detailsSectionId, optionalParameters);
126138
}
@@ -132,14 +144,23 @@ private void documentMojo(Plugin plugin, Mojo mojo) throws IOException {
132144
}
133145
}
134146

147+
private String goalSectionId(Mojo mojo) {
148+
String goalSection = this.goalSections.get(mojo.getGoal());
149+
if (goalSection == null) {
150+
throw new IllegalStateException("Goal '" + mojo.getGoal() + "' has not be assigned to a section");
151+
}
152+
String sectionId = goalSection + "." + mojo.getGoal() + "-goal";
153+
return sectionId;
154+
}
155+
135156
private void writeParametersTable(PrintWriter writer, String detailsSectionId, List<Parameter> parameters) {
136157
writer.println("[cols=\"3,2,3\"]");
137158
writer.println("|===");
138159
writer.println("| Name | Type | Default");
139160
writer.println();
140161
for (Parameter parameter : parameters) {
141162
String name = parameter.getName();
142-
writer.printf("| <<%s-%s,%s>>%n", detailsSectionId, name, name);
163+
writer.printf("| <<%s.%s,%s>>%n", detailsSectionId, parameterId(name), name);
143164
writer.printf("| `%s`%n", typeNameToJavadocLink(shortTypeName(parameter.getType()), parameter.getType()));
144165
String defaultValue = parameter.getDefaultValue();
145166
if (defaultValue != null) {
@@ -158,7 +179,7 @@ private void writeParameterDetails(PrintWriter writer, List<Parameter> parameter
158179
String name = parameter.getName();
159180
writer.println();
160181
writer.println();
161-
writer.printf("[[%s-%s]]%n", sectionId, name);
182+
writer.printf("[[%s.%s]]%n", sectionId, parameterId(name));
162183
writer.printf("=== `%s`%n", name);
163184
writer.println(parameter.getDescription());
164185
writer.println();
@@ -174,6 +195,20 @@ private void writeParameterDetails(PrintWriter writer, List<Parameter> parameter
174195
}
175196
}
176197

198+
private String parameterId(String name) {
199+
StringBuilder id = new StringBuilder(name.length() + 4);
200+
for (char c : name.toCharArray()) {
201+
if (Character.isLowerCase(c)) {
202+
id.append(c);
203+
}
204+
else {
205+
id.append("-");
206+
id.append(Character.toLowerCase(c));
207+
}
208+
}
209+
return id.toString();
210+
}
211+
177212
private void writeDetail(PrintWriter writer, String name, String value) {
178213
writer.printf("| %s%n", name);
179214
writer.printf("| `%s`%n", value);

Diff for: ‎spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/build.gradle

+14
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@ configurations {
1313
}
1414

1515
dependencies {
16+
asciidoctorExtensions("io.spring.asciidoctor:spring-asciidoctor-extensions-section-ids")
17+
1618
compileOnly("org.apache.maven.plugin-tools:maven-plugin-annotations")
1719
compileOnly("org.sonatype.plexus:plexus-build-api")
1820
compileOnly("org.apache.maven.shared:maven-common-artifact-filters") {
@@ -142,3 +144,15 @@ prepareMavenBinaries {
142144
artifacts {
143145
"documentation" zip
144146
}
147+
148+
tasks.named("documentPluginGoals") {
149+
goalSections = [
150+
"build-image": "build-image",
151+
"build-info": "build-info",
152+
"help": "help",
153+
"repackage": "packaging",
154+
"run": "run",
155+
"start": "integration-tests",
156+
"stop": "integration-tests"
157+
]
158+
}

Diff for: ‎spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/anchor-rewrite.properties

+114
Original file line numberDiff line numberDiff line change
@@ -33,3 +33,117 @@ run-example-active-profiles=run.examples.specify-active-profiles
3333
using-parent-pom=using.parent-pom
3434
using-import=using.import
3535
using-overriding-command-line=using.overriding-command-line
36+
37+
# Consistent section IDs for goals
38+
goals-build-image=build-image.build-image-goal
39+
goals-build-image-parameters-details=build-image.build-image-goal.parameter-details
40+
goals-build-image-parameters-details-classifier=build-image.build-image-goal.parameter-details.classifier
41+
goals-build-image-parameters-details-docker=build-image.build-image-goal.parameter-details.docker
42+
goals-build-image-parameters-details-excludeDevtools=build-image.build-image-goal.parameter-details.exclude-devtools
43+
goals-build-image-parameters-details-excludeGroupIds=build-image.build-image-goal.parameter-details.exclude-group-ids
44+
goals-build-image-parameters-details-excludes=build-image.build-image-goal.parameter-details.excludes
45+
goals-build-image-parameters-details-image=build-image.build-image-goal.parameter-details.image
46+
goals-build-image-parameters-details-includeSystemScope=build-image.build-image-goal.parameter-details.include-system-scope
47+
goals-build-image-parameters-details-includes=build-image.build-image-goal.parameter-details.includes
48+
goals-build-image-parameters-details-layers=build-image.build-image-goal.parameter-details.layers
49+
goals-build-image-parameters-details-layout=build-image.build-image-goal.parameter-details.layout
50+
goals-build-image-parameters-details-layoutFactory=build-image.build-image-goal.parameter-details.layout-factory
51+
goals-build-image-parameters-details-mainClass=build-image.build-image-goal.parameter-details.main-class
52+
goals-build-image-parameters-details-skip=build-image.build-image-goal.parameter-details.skip
53+
goals-build-image-parameters-details-sourceDirectory=build-image.build-image-goal.parameter-details.source-directory
54+
goals-build-image-parameters-optional=build-image.build-image-goal.optional-parameters
55+
goals-build-image-parameters-required=build-image.build-image-goal.required-parameters
56+
goals-build-info=build-info.build-info-goal
57+
goals-build-info-parameters-details=build-info.build-info-goal.parameter-details
58+
goals-build-info-parameters-details-additionalProperties=build-info.build-info-goal.parameter-details.additional-properties
59+
goals-build-info-parameters-details-excludeInfoProperties=build-info.build-info-goal.parameter-details.exclude-info-properties
60+
goals-build-info-parameters-details-outputFile=build-info.build-info-goal.parameter-details.output-file
61+
goals-build-info-parameters-details-time=build-info.build-info-goal.parameter-details.time
62+
goals-build-info-parameters-optional=build-info.build-info-goal.optional-parameters
63+
goals-help=help.help-goal
64+
goals-help-parameters-details=help.help-goal.parameter-details
65+
goals-help-parameters-details-detail=help.help-goal.parameter-details.detail
66+
goals-help-parameters-details-goal=help.help-goal.parameter-details.goal
67+
goals-help-parameters-details-indentSize=help.help-goal.parameter-details.indent-size
68+
goals-help-parameters-details-lineLength=help.help-goal.parameter-details.line-length
69+
goals-help-parameters-optional=help.help-goal.optional-parameters
70+
goals-repackage=packaging.repackage-goal
71+
goals-repackage-parameters-details=packaging.repackage-goal.parameter-details
72+
goals-repackage-parameters-details-attach=packaging.repackage-goal.parameter-details.attach
73+
goals-repackage-parameters-details-classifier=packaging.repackage-goal.parameter-details.classifier
74+
goals-repackage-parameters-details-embeddedLaunchScript=packaging.repackage-goal.parameter-details.embedded-launch-script
75+
goals-repackage-parameters-details-embeddedLaunchScriptProperties=packaging.repackage-goal.parameter-details.embedded-launch-script-properties
76+
goals-repackage-parameters-details-excludeDevtools=packaging.repackage-goal.parameter-details.exclude-devtools
77+
goals-repackage-parameters-details-excludeGroupIds=packaging.repackage-goal.parameter-details.exclude-group-ids
78+
goals-repackage-parameters-details-excludes=packaging.repackage-goal.parameter-details.excludes
79+
goals-repackage-parameters-details-executable=packaging.repackage-goal.parameter-details.executable
80+
goals-repackage-parameters-details-includeSystemScope=packaging.repackage-goal.parameter-details.include-system-scope
81+
goals-repackage-parameters-details-includes=packaging.repackage-goal.parameter-details.includes
82+
goals-repackage-parameters-details-layers=packaging.repackage-goal.parameter-details.layers
83+
goals-repackage-parameters-details-layout=packaging.repackage-goal.parameter-details.layout
84+
goals-repackage-parameters-details-layoutFactory=packaging.repackage-goal.parameter-details.layout-factory
85+
goals-repackage-parameters-details-mainClass=packaging.repackage-goal.parameter-details.main-class
86+
goals-repackage-parameters-details-outputDirectory=packaging.repackage-goal.parameter-details.output-directory
87+
goals-repackage-parameters-details-outputTimestamp=packaging.repackage-goal.parameter-details.output-timestamp
88+
goals-repackage-parameters-details-requiresUnpack=packaging.repackage-goal.parameter-details.requires-unpack
89+
goals-repackage-parameters-details-skip=packaging.repackage-goal.parameter-details.skip
90+
goals-repackage-parameters-optional=packaging.repackage-goal.optional-parameters
91+
goals-repackage-parameters-required=packaging.repackage-goal.required-parameters
92+
goals-run=run.run-goal
93+
goals-run-parameters-details=run.run-goal.parameter-details
94+
goals-run-parameters-details-addResources=run.run-goal.parameter-details.add-resources
95+
goals-run-parameters-details-agents=run.run-goal.parameter-details.agents
96+
goals-run-parameters-details-arguments=run.run-goal.parameter-details.arguments
97+
goals-run-parameters-details-classesDirectory=run.run-goal.parameter-details.classes-directory
98+
goals-run-parameters-details-commandlineArguments=run.run-goal.parameter-details.commandline-arguments
99+
goals-run-parameters-details-directories=run.run-goal.parameter-details.directories
100+
goals-run-parameters-details-environmentVariables=run.run-goal.parameter-details.environment-variables
101+
goals-run-parameters-details-excludeGroupIds=run.run-goal.parameter-details.exclude-group-ids
102+
goals-run-parameters-details-excludes=run.run-goal.parameter-details.excludes
103+
goals-run-parameters-details-fork=run.run-goal.parameter-details.fork
104+
goals-run-parameters-details-includes=run.run-goal.parameter-details.includes
105+
goals-run-parameters-details-jvmArguments=run.run-goal.parameter-details.jvm-arguments
106+
goals-run-parameters-details-mainClass=run.run-goal.parameter-details.main-class
107+
goals-run-parameters-details-noverify=run.run-goal.parameter-details.noverify
108+
goals-run-parameters-details-optimizedLaunch=run.run-goal.parameter-details.optimized-launch
109+
goals-run-parameters-details-profiles=run.run-goal.parameter-details.profiles
110+
goals-run-parameters-details-skip=run.run-goal.parameter-details.skip
111+
goals-run-parameters-details-systemPropertyVariables=run.run-goal.parameter-details.system-property-variables
112+
goals-run-parameters-details-useTestClasspath=run.run-goal.parameter-details.use-test-classpath
113+
goals-run-parameters-details-workingDirectory=run.run-goal.parameter-details.working-directory
114+
goals-run-parameters-optional=run.run-goal.optional-parameters
115+
goals-run-parameters-required=run.run-goal.required-parameters
116+
goals-start=integration-tests.start-goal
117+
goals-start-parameters-details=integration-tests.start-goal.parameter-details
118+
goals-start-parameters-details-addResources=integration-tests.start-goal.parameter-details.add-resources
119+
goals-start-parameters-details-agents=integration-tests.start-goal.parameter-details.agents
120+
goals-start-parameters-details-arguments=integration-tests.start-goal.parameter-details.arguments
121+
goals-start-parameters-details-classesDirectory=integration-tests.start-goal.parameter-details.classes-directory
122+
goals-start-parameters-details-commandlineArguments=integration-tests.start-goal.parameter-details.commandline-arguments
123+
goals-start-parameters-details-directories=integration-tests.start-goal.parameter-details.directories
124+
goals-start-parameters-details-environmentVariables=integration-tests.start-goal.parameter-details.environment-variables
125+
goals-start-parameters-details-excludeGroupIds=integration-tests.start-goal.parameter-details.exclude-group-ids
126+
goals-start-parameters-details-excludes=integration-tests.start-goal.parameter-details.excludes
127+
goals-start-parameters-details-fork=integration-tests.start-goal.parameter-details.fork
128+
goals-start-parameters-details-includes=integration-tests.start-goal.parameter-details.includes
129+
goals-start-parameters-details-jmxName=integration-tests.start-goal.parameter-details.jmx-name
130+
goals-start-parameters-details-jmxPort=integration-tests.start-goal.parameter-details.jmx-port
131+
goals-start-parameters-details-jvmArguments=integration-tests.start-goal.parameter-details.jvm-arguments
132+
goals-start-parameters-details-mainClass=integration-tests.start-goal.parameter-details.main-class
133+
goals-start-parameters-details-maxAttempts=integration-tests.start-goal.parameter-details.max-attempts
134+
goals-start-parameters-details-noverify=integration-tests.start-goal.parameter-details.noverify
135+
goals-start-parameters-details-profiles=integration-tests.start-goal.parameter-details.profiles
136+
goals-start-parameters-details-skip=integration-tests.start-goal.parameter-details.skip
137+
goals-start-parameters-details-systemPropertyVariables=integration-tests.start-goal.parameter-details.system-property-variables
138+
goals-start-parameters-details-useTestClasspath=integration-tests.start-goal.parameter-details.use-test-classpath
139+
goals-start-parameters-details-wait=integration-tests.start-goal.parameter-details.wait
140+
goals-start-parameters-details-workingDirectory=integration-tests.start-goal.parameter-details.working-directory
141+
goals-start-parameters-optional=integration-tests.start-goal.optional-parameters
142+
goals-start-parameters-required=integration-tests.start-goal.required-parameters
143+
goals-stop=integration-tests.stop-goal
144+
goals-stop-parameters-details=integration-tests.stop-goal.parameter-details
145+
goals-stop-parameters-details-fork=integration-tests.stop-goal.parameter-details.fork
146+
goals-stop-parameters-details-jmxName=integration-tests.stop-goal.parameter-details.jmx-name
147+
goals-stop-parameters-details-jmxPort=integration-tests.stop-goal.parameter-details.jmx-port
148+
goals-stop-parameters-details-skip=integration-tests.stop-goal.parameter-details.skip
149+
goals-stop-parameters-optional=integration-tests.stop-goal.optional-parameters

Diff for: ‎spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/packaging.adoc

+1-1
Original file line numberDiff line numberDiff line change
@@ -210,7 +210,7 @@ include::../maven/packaging/custom-layout-pom.xml[tags=custom-layout]
210210
The layout factory is provided as an implementation of `LayoutFactory` (from `spring-boot-loader-tools`) explicitly specified in the pom.
211211
If there is only one custom `LayoutFactory` on the plugin classpath and it is listed in `META-INF/spring.factories` then it is unnecessary to explicitly set it in the plugin configuration.
212212

213-
Layout factories are always ignored if an explicit <<goals-repackage-parameters-details-layoutFactory,layout>> is set.
213+
Layout factories are always ignored if an explicit <<packaging.repackage-goal.parameter-details.layout-factory,layout>> is set.
214214

215215

216216

Diff for: ‎spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/using.adoc

+1-1
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ The parent project provides the following features:
88
* Compilation with `-parameters`.
99
* A dependency management section, inherited from the `spring-boot-dependencies` POM, that manages the versions of common dependencies.
1010
This dependency management lets you omit `<version>` tags for those dependencies when used in your own POM.
11-
* An execution of the <<goals.adoc#goals-repackage, `repackage` goal>> with a `repackage` execution id.
11+
* An execution of the <<goals.adoc#packaging.repackage-goal, `repackage` goal>> with a `repackage` execution id.
1212
* Sensible https://maven.apache.org/plugins/maven-resources-plugin/examples/filter.html[resource filtering].
1313
* Sensible plugin configuration (https://github.com/ktoso/maven-git-commit-id-plugin[Git commit ID], and https://maven.apache.org/plugins/maven-shade-plugin/[shade]).
1414
* Sensible resource filtering for `application.properties` and `application.yml` including profile-specific files (for example, `application-dev.properties` and `application-dev.yml`)

0 commit comments

Comments
 (0)