From 2d9b1ad59279f177dbece8583dbe08cc8abd906d Mon Sep 17 00:00:00 2001 From: Moritz Halbritter Date: Tue, 26 Mar 2024 10:11:47 +0100 Subject: [PATCH] Use xref for documentation links Closes gh-33745 --- .../build/context/properties/CompoundRow.java | 7 +- .../build/context/properties/SingleRow.java | 5 +- .../mavenplugin/DocumentPluginGoals.java | 2 +- .../boot/build/starters/DocumentStarters.java | 4 +- .../context/properties/CompoundRowTests.java | 7 +- .../context/properties/SingleRowTests.java | 17 +-- .../build/context/properties/TableTests.java | 7 +- .../api/pages/rest/actuator/index.adoc | 4 +- .../modules/maven-plugin/pages/packaging.adoc | 2 +- .../modules/maven-plugin/pages/using.adoc | 2 +- .../groovy/generateGoalsDocumentation.groovy | 129 ------------------ 11 files changed, 31 insertions(+), 155 deletions(-) delete mode 100644 spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/main/groovy/generateGoalsDocumentation.groovy diff --git a/buildSrc/src/main/java/org/springframework/boot/build/context/properties/CompoundRow.java b/buildSrc/src/main/java/org/springframework/boot/build/context/properties/CompoundRow.java index d322ce1062..ffa9f5687b 100644 --- a/buildSrc/src/main/java/org/springframework/boot/build/context/properties/CompoundRow.java +++ b/buildSrc/src/main/java/org/springframework/boot/build/context/properties/CompoundRow.java @@ -1,5 +1,5 @@ /* - * Copyright 2012-2021 the original author or authors. + * Copyright 2012-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. @@ -24,6 +24,7 @@ import java.util.TreeSet; * * @author Brian Clozel * @author Phillip Webb + * @author Moritz Halbritter */ class CompoundRow extends Row { @@ -45,9 +46,9 @@ class CompoundRow extends Row { void write(Asciidoc asciidoc) { asciidoc.append("|"); asciidoc.append("[[" + getAnchor() + "]]"); - asciidoc.append("<<" + getAnchor() + ","); + asciidoc.append("xref:#" + getAnchor() + "["); this.propertyNames.forEach(asciidoc::appendWithHardLineBreaks); - asciidoc.appendln(">>"); + asciidoc.appendln("]"); asciidoc.appendln("|+++", this.description, "+++"); asciidoc.appendln("|"); } diff --git a/buildSrc/src/main/java/org/springframework/boot/build/context/properties/SingleRow.java b/buildSrc/src/main/java/org/springframework/boot/build/context/properties/SingleRow.java index 65f6bb3625..c81f57c9f4 100644 --- a/buildSrc/src/main/java/org/springframework/boot/build/context/properties/SingleRow.java +++ b/buildSrc/src/main/java/org/springframework/boot/build/context/properties/SingleRow.java @@ -1,5 +1,5 @@ /* - * Copyright 2012-2023 the original author or authors. + * Copyright 2012-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. @@ -24,6 +24,7 @@ import java.util.stream.Collectors; * * @author Brian Clozel * @author Phillip Webb + * @author Moritz Halbritter */ class SingleRow extends Row { @@ -56,7 +57,7 @@ class SingleRow extends Row { void write(Asciidoc asciidoc) { asciidoc.append("|"); asciidoc.append("[[" + getAnchor() + "]]"); - asciidoc.appendln("<<" + getAnchor() + ",`+", this.displayName, "+`>>"); + asciidoc.appendln("xref:#" + getAnchor() + "[`+", this.displayName, "+`]"); writeDescription(asciidoc); writeDefaultValue(asciidoc); } diff --git a/buildSrc/src/main/java/org/springframework/boot/build/mavenplugin/DocumentPluginGoals.java b/buildSrc/src/main/java/org/springframework/boot/build/mavenplugin/DocumentPluginGoals.java index 11c75f12aa..927241d00e 100644 --- a/buildSrc/src/main/java/org/springframework/boot/build/mavenplugin/DocumentPluginGoals.java +++ b/buildSrc/src/main/java/org/springframework/boot/build/mavenplugin/DocumentPluginGoals.java @@ -158,7 +158,7 @@ public class DocumentPluginGoals extends DefaultTask { writer.println(); for (Parameter parameter : parameters) { String name = parameter.getName(); - writer.printf("| <<%s.%s,%s>>%n", detailsSectionId, parameterId(name), name); + writer.printf("| xref:#%s.%s[%s]%n", detailsSectionId, parameterId(name), name); writer.printf("| `%s`%n", typeNameToJavadocLink(shortTypeName(parameter.getType()), parameter.getType())); String defaultValue = parameter.getDefaultValue(); if (defaultValue != null) { diff --git a/buildSrc/src/main/java/org/springframework/boot/build/starters/DocumentStarters.java b/buildSrc/src/main/java/org/springframework/boot/build/starters/DocumentStarters.java index 669eeb40a0..0e180ae696 100644 --- a/buildSrc/src/main/java/org/springframework/boot/build/starters/DocumentStarters.java +++ b/buildSrc/src/main/java/org/springframework/boot/build/starters/DocumentStarters.java @@ -1,5 +1,5 @@ /* - * Copyright 2012-2023 the original author or authors. + * Copyright 2012-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. @@ -128,7 +128,7 @@ public class DocumentStarters extends DefaultTask { } private String addStarterCrossLinks(String input) { - return input.replaceAll("(spring-boot-starter[A-Za-z-]*)", "<<$1,`$1`>>"); + return input.replaceAll("(spring-boot-starter[A-Za-z-]*)", "xref:#$1[`$1`]"); } private static final class Starter implements Comparable { diff --git a/buildSrc/src/test/java/org/springframework/boot/build/context/properties/CompoundRowTests.java b/buildSrc/src/test/java/org/springframework/boot/build/context/properties/CompoundRowTests.java index 887e01bf75..4e6949e3f6 100644 --- a/buildSrc/src/test/java/org/springframework/boot/build/context/properties/CompoundRowTests.java +++ b/buildSrc/src/test/java/org/springframework/boot/build/context/properties/CompoundRowTests.java @@ -1,5 +1,5 @@ /* - * Copyright 2012-2023 the original author or authors. + * Copyright 2012-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. @@ -24,6 +24,7 @@ import static org.assertj.core.api.Assertions.assertThat; * Tests for {@link CompoundRow}. * * @author Brian Clozel + * @author Moritz Halbritter */ class CompoundRowTests { @@ -39,8 +40,8 @@ class CompoundRowTests { row.addProperty(new ConfigurationProperty("spring.test.third", "java.lang.String")); Asciidoc asciidoc = new Asciidoc(); row.write(asciidoc); - assertThat(asciidoc).hasToString("|[[my.spring.test]]<>" + NEWLINE + assertThat(asciidoc).hasToString("|[[my.spring.test]]xref:#my.spring.test[`+spring.test.first+` +" + NEWLINE + + "`+spring.test.second+` +" + NEWLINE + "`+spring.test.third+` +" + NEWLINE + "]" + NEWLINE + "|+++This is a description.+++" + NEWLINE + "|" + NEWLINE); } diff --git a/buildSrc/src/test/java/org/springframework/boot/build/context/properties/SingleRowTests.java b/buildSrc/src/test/java/org/springframework/boot/build/context/properties/SingleRowTests.java index b1e48d8dff..5d046a71ef 100644 --- a/buildSrc/src/test/java/org/springframework/boot/build/context/properties/SingleRowTests.java +++ b/buildSrc/src/test/java/org/springframework/boot/build/context/properties/SingleRowTests.java @@ -1,5 +1,5 @@ /* - * Copyright 2012-2023 the original author or authors. + * Copyright 2012-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. @@ -24,6 +24,7 @@ import static org.assertj.core.api.Assertions.assertThat; * Tests for {@link SingleRow}. * * @author Brian Clozel + * @author Moritz Halbritter */ class SingleRowTests { @@ -38,7 +39,7 @@ class SingleRowTests { SingleRow row = new SingleRow(SNIPPET, property); Asciidoc asciidoc = new Asciidoc(); row.write(asciidoc); - assertThat(asciidoc).hasToString("|[[my.spring.test.prop]]<>" + assertThat(asciidoc).hasToString("|[[my.spring.test.prop]]xref:#my.spring.test.prop[`+spring.test.prop+`]" + NEWLINE + "|+++This is a description.+++" + NEWLINE + "|`+something+`" + NEWLINE); } @@ -49,7 +50,7 @@ class SingleRowTests { SingleRow row = new SingleRow(SNIPPET, property); Asciidoc asciidoc = new Asciidoc(); row.write(asciidoc); - assertThat(asciidoc).hasToString("|[[my.spring.test.prop]]<>" + assertThat(asciidoc).hasToString("|[[my.spring.test.prop]]xref:#my.spring.test.prop[`+spring.test.prop+`]" + NEWLINE + "|+++This is a description.+++" + NEWLINE + "|" + NEWLINE); } @@ -60,7 +61,7 @@ class SingleRowTests { SingleRow row = new SingleRow(SNIPPET, property); Asciidoc asciidoc = new Asciidoc(); row.write(asciidoc); - assertThat(asciidoc).hasToString("|[[my.spring.test.prop]]<>" + assertThat(asciidoc).hasToString("|[[my.spring.test.prop]]xref:#my.spring.test.prop[`+spring.test.prop+`]" + NEWLINE + "|+++This is a description.+++" + NEWLINE + "|`+first\\|second+`" + NEWLINE); } @@ -71,7 +72,7 @@ class SingleRowTests { SingleRow row = new SingleRow(SNIPPET, property); Asciidoc asciidoc = new Asciidoc(); row.write(asciidoc); - assertThat(asciidoc).hasToString("|[[my.spring.test.prop]]<>" + assertThat(asciidoc).hasToString("|[[my.spring.test.prop]]xref:#my.spring.test.prop[`+spring.test.prop+`]" + NEWLINE + "|+++This is a description.+++" + NEWLINE + "|`+first\\\\second+`" + NEWLINE); } @@ -82,7 +83,7 @@ class SingleRowTests { SingleRow row = new SingleRow(SNIPPET, property); Asciidoc asciidoc = new Asciidoc(); row.write(asciidoc); - assertThat(asciidoc).hasToString("|[[my.spring.test.prop]]<>" + assertThat(asciidoc).hasToString("|[[my.spring.test.prop]]xref:#my.spring.test.prop[`+spring.test.prop+`]" + NEWLINE + "|+++This is a description with a \\| pipe.+++" + NEWLINE + "|" + NEWLINE); } @@ -93,7 +94,7 @@ class SingleRowTests { SingleRow row = new SingleRow(SNIPPET, property); Asciidoc asciidoc = new Asciidoc(); row.write(asciidoc); - assertThat(asciidoc).hasToString("|[[my.spring.test.prop]]<>" + assertThat(asciidoc).hasToString("|[[my.spring.test.prop]]xref:#my.spring.test.prop[`+spring.test.prop.*+`]" + NEWLINE + "|+++This is a description.+++" + NEWLINE + "|" + NEWLINE); } @@ -105,7 +106,7 @@ class SingleRowTests { SingleRow row = new SingleRow(SNIPPET, property); Asciidoc asciidoc = new Asciidoc(); row.write(asciidoc); - assertThat(asciidoc).hasToString("|[[my.spring.test.prop]]<>" + assertThat(asciidoc).hasToString("|[[my.spring.test.prop]]xref:#my.spring.test.prop[`+spring.test.prop+`]" + NEWLINE + "|+++This is a description.+++" + NEWLINE + "|`+first," + NEWLINE + "second," + NEWLINE + "third+`" + NEWLINE); } diff --git a/buildSrc/src/test/java/org/springframework/boot/build/context/properties/TableTests.java b/buildSrc/src/test/java/org/springframework/boot/build/context/properties/TableTests.java index 618218a6eb..2ed509fbb9 100644 --- a/buildSrc/src/test/java/org/springframework/boot/build/context/properties/TableTests.java +++ b/buildSrc/src/test/java/org/springframework/boot/build/context/properties/TableTests.java @@ -1,5 +1,5 @@ /* - * Copyright 2012-2023 the original author or authors. + * Copyright 2012-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. @@ -24,6 +24,7 @@ import static org.assertj.core.api.Assertions.assertThat; * Tests for {@link Table}. * * @author Brian Clozel + * @author Moritz Halbritter */ class TableTests { @@ -44,10 +45,10 @@ class TableTests { assertThat(asciidoc).hasToString("[cols=\"4,3,3\", options=\"header\"]" + NEWLINE + "|===" + NEWLINE + "|Name|Description|Default Value" + NEWLINE + NEWLINE + - "|[[my.spring.test.other]]<>" + NEWLINE + + "|[[my.spring.test.other]]xref:#my.spring.test.other[`+spring.test.other+`]" + NEWLINE + "|+++This is another description.+++" + NEWLINE + "|`+other value+`" + NEWLINE + NEWLINE + - "|[[my.spring.test.prop]]<>" + NEWLINE + + "|[[my.spring.test.prop]]xref:#my.spring.test.prop[`+spring.test.prop+`]" + NEWLINE + "|+++This is a description.+++" + NEWLINE + "|`+something+`" + NEWLINE + NEWLINE + "|===" + NEWLINE); diff --git a/spring-boot-project/spring-boot-actuator-autoconfigure/src/docs/antora/modules/api/pages/rest/actuator/index.adoc b/spring-boot-project/spring-boot-actuator-autoconfigure/src/docs/antora/modules/api/pages/rest/actuator/index.adoc index 76677f10fc..3420016877 100644 --- a/spring-boot-project/spring-boot-actuator-autoconfigure/src/docs/antora/modules/api/pages/rest/actuator/index.adoc +++ b/spring-boot-project/spring-boot-actuator-autoconfigure/src/docs/antora/modules/api/pages/rest/actuator/index.adoc @@ -6,8 +6,8 @@ This API documentation describes Spring Boot Actuators web endpoints. Before you proceed, you should read the following topics: -* <> -* <> +* xref:#overview.endpoint-urls[] +* xref:#overview.timestamps[] NOTE: In order to get the correct JSON responses documented below, Jackson must be available. diff --git a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/antora/modules/maven-plugin/pages/packaging.adoc b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/antora/modules/maven-plugin/pages/packaging.adoc index 2091ba7b81..243df6ffe0 100644 --- a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/antora/modules/maven-plugin/pages/packaging.adoc +++ b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/antora/modules/maven-plugin/pages/packaging.adoc @@ -217,7 +217,7 @@ include::example$packaging/custom-layout-pom.xml[tags=custom-layout] The layout factory is provided as an implementation of `LayoutFactory` (from `spring-boot-loader-tools`) explicitly specified in the pom. 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. -Layout factories are always ignored if an explicit <> is set. +Layout factories are always ignored if an explicit xref:#packaging.repackage-goal.parameter-details.layout-factory[layout] is set. diff --git a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/antora/modules/maven-plugin/pages/using.adoc b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/antora/modules/maven-plugin/pages/using.adoc index c54861dd49..b227f433d5 100644 --- a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/antora/modules/maven-plugin/pages/using.adoc +++ b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/antora/modules/maven-plugin/pages/using.adoc @@ -9,7 +9,7 @@ The parent project provides the following features: * Compilation with `-parameters`. * A dependency management section, inherited from the `spring-boot-dependencies` POM, that manages the versions of common dependencies. This dependency management lets you omit `` tags for those dependencies when used in your own POM. -* An execution of the <> with a `repackage` execution id. +* An execution of the xref:maven-plugin:packaging.adoc#packaging.repackage-goal[`repackage` goal] with a `repackage` execution id. * A `native` profile that configures the build to be able to generate a Native image. * Sensible https://maven.apache.org/plugins/maven-resources-plugin/examples/filter.html[resource filtering]. * 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]). diff --git a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/main/groovy/generateGoalsDocumentation.groovy b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/main/groovy/generateGoalsDocumentation.groovy deleted file mode 100644 index a7542748de..0000000000 --- a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/main/groovy/generateGoalsDocumentation.groovy +++ /dev/null @@ -1,129 +0,0 @@ -import groovy.util.XmlSlurper - -private String format(String input) { - input.replace("", "`") - .replace("", "`") - .replace("<", "<") - .replace(">", ">") - .replace("
", " ") - .replace("\n", " ") - .replace(""", '"') - .replaceAll('\\{@code (.*?)\\}', '`$1`') - .replaceAll('\\{@link (.*?)\\}', '`$1`') - .replaceAll('\\{@literal (.*?)\\}', '`$1`') - .replaceAll('(.*?)', '\$1[\$2]') -} - -private writeParametersTable(PrintWriter writer, def goal, def parameters, def configuration) { - writer.println '[cols="3,2,3"]' - writer.println '|===' - writer.println '| Name | Type | Default' - writer.println() - parameters.each { parameter -> - def name = parameter.name.text() - writer.println("| <>") - def type = parameter.type.text() - if (type.lastIndexOf('.') >= 0) { - type = type.substring(type.lastIndexOf('.') + 1) - } - writer.println("| `$type`") - def defaultValue = "${configuration[name].@'default-value'}" - if (defaultValue) { - writer.println("| `$defaultValue`") - } - else { - writer.println("|") - } - writer.println() - } - writer.println '|===' -} - -private writeParameterDetails(PrintWriter writer, def parameters, def configuration, def sectionId) { - parameters.each { parameter -> - def name = parameter.name.text() - writer.println "[[$sectionId-$name]]" - writer.println "==== `$name`" - writer.println(format(parameter.description.text())) - writer.println() - writer.println '[cols="10h,90"]' - writer.println '|===' - writer.println() - writer.println '| Name' - writer.println "| `$name`" - writer.println '| Type' - def type = parameter.type.text() - if (type.lastIndexOf('.') >= 0) { - type = type.substring(type.lastIndexOf('.') + 1) - } - writer.println("| `$type`") - def defaultValue = "${configuration[name].@'default-value'}" - if (defaultValue) { - writer.println '| Default value' - writer.println("| `$defaultValue`") - } - def userProperty = "${configuration[name].text().replace('${', '`').replace('}', '`')}" - writer.println '| User property' - userProperty ? writer.println("| ${userProperty}") : writer.println("|") - writer.println '| Since' - def since = parameter.since.text() - since ? writer.println("| `${since}`") : writer.println("|") - writer.println '| Required' - writer.println "| ${parameter.required.text()}" - writer.println() - writer.println '|===' - } -} - -def plugin = new XmlSlurper().parse("${project.build.outputDirectory}/META-INF/maven/plugin.xml" as File) -String goalPrefix = plugin.goalPrefix.text() -File goalsDir = new File(project.build.directory, "generated-resources/goals/") -goalsDir.mkdirs() - -new File(goalsDir, "overview.adoc").withPrintWriter { writer -> - writer.println '[cols="1,3"]' - writer.println '|===' - writer.println '| Goal | Description' - writer.println() - plugin.mojos.mojo.each { mojo -> - def goal = mojo.goal.text() - writer.println "| <>" - writer.println "| ${format(mojo.description.text())}" - writer.println() - } - writer.println '|===' -} - -plugin.mojos.mojo.each { mojo -> - String goal = mojo.goal.text() - new File(goalsDir, "${goal}.adoc").withPrintWriter { writer -> - def sectionId = "goals-$goal" - writer.println() - writer.println("[[$sectionId]]") - writer.println("== `$goalPrefix:$goal`") - writer.println("`${plugin.groupId.text()}:${plugin.artifactId.text()}:${plugin.version.text()}:${mojo.goal.text()}`") - writer.println() - writer.println(format(mojo.description.text())) - writer.println() - def parameters = mojo.parameters.parameter.findAll { it.editable.text() == 'true' } - def requiredParameters = parameters.findAll { it.required.text() == 'true' } - if (requiredParameters.size()) { - writer.println("[[$sectionId-parameters-required]]") - writer.println("=== Required parameters") - writeParametersTable(writer, goal, requiredParameters, mojo.configuration) - writer.println() - } - def optionalParameters = parameters.findAll { it.required.text() == 'false' } - if (optionalParameters.size()) { - writer.println("[[$sectionId-parameters-optional]]") - writer.println("=== Optional parameters") - writeParametersTable(writer, goal, optionalParameters, mojo.configuration) - writer.println() - } - def detailsSectionId = "$sectionId-parameters-details" - writer.println("[[$detailsSectionId]]") - writer.println("=== Parameter details") - writeParameterDetails(writer, parameters, mojo.configuration, detailsSectionId) - writer.println() - } -}