Use xref for documentation links

Closes gh-33745

Author: mhalbritter

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 @@
  *
  * @author Brian Clozel
  * @author Phillip Webb
+ * @author Moritz Halbritter
  */
 class CompoundRow extends Row {
 
@@ -45,9 +46,9 @@ void addProperty(ConfigurationProperty property) {
 	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("|");
 	}

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 @@
  *
  * @author Brian Clozel
  * @author Phillip Webb
+ * @author Moritz Halbritter
  */
 class SingleRow extends Row {
 
@@ -56,7 +57,7 @@ private String getDefaultValue(Object defaultValue) {
 	void write(Asciidoc asciidoc) {
 		asciidoc.append("|");
 		asciidoc.append("[[" + getAnchor() + "]]");
-		asciidoc.appendln("<<" + getAnchor() + ",`+", this.displayName, "+`>>");
+		asciidoc.appendln("xref:#" + getAnchor() + "[`+", this.displayName, "+`]");
 		writeDescription(asciidoc);
 		writeDefaultValue(asciidoc);
 	}

buildSrc/src/main/java/org/springframework/boot/build/mavenplugin/DocumentPluginGoals.java

@@ -158,7 +158,7 @@ private void writeParametersTable(PrintWriter writer, String detailsSectionId, L
 		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) {

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 @@ private String postProcessDescription(String description) {
 	}
 
 	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<Starter> {

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 @@
  * Tests for {@link CompoundRow}.
  *
  * @author Brian Clozel
+ * @author Moritz Halbritter
  */
 class CompoundRowTests {
 
@@ -39,8 +40,8 @@ void simpleProperty() {
 		row.addProperty(new ConfigurationProperty("spring.test.third", "java.lang.String"));
 		Asciidoc asciidoc = new Asciidoc();
 		row.write(asciidoc);
-		assertThat(asciidoc).hasToString("|[[my.spring.test]]<<my.spring.test,`+spring.test.first+` +" + NEWLINE
-				+ "`+spring.test.second+` +" + NEWLINE + "`+spring.test.third+` +" + NEWLINE + ">>" + 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);
 	}
 

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 @@
  * Tests for {@link SingleRow}.
  *
  * @author Brian Clozel
+ * @author Moritz Halbritter
  */
 class SingleRowTests {
 
@@ -38,7 +39,7 @@ void simpleProperty() {
 		SingleRow row = new SingleRow(SNIPPET, property);
 		Asciidoc asciidoc = new Asciidoc();
 		row.write(asciidoc);
-		assertThat(asciidoc).hasToString("|[[my.spring.test.prop]]<<my.spring.test.prop,`+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 @@ void noDefaultValue() {
 		SingleRow row = new SingleRow(SNIPPET, property);
 		Asciidoc asciidoc = new Asciidoc();
 		row.write(asciidoc);
-		assertThat(asciidoc).hasToString("|[[my.spring.test.prop]]<<my.spring.test.prop,`+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 @@ void defaultValueWithPipes() {
 		SingleRow row = new SingleRow(SNIPPET, property);
 		Asciidoc asciidoc = new Asciidoc();
 		row.write(asciidoc);
-		assertThat(asciidoc).hasToString("|[[my.spring.test.prop]]<<my.spring.test.prop,`+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 @@ void defaultValueWithBackslash() {
 		SingleRow row = new SingleRow(SNIPPET, property);
 		Asciidoc asciidoc = new Asciidoc();
 		row.write(asciidoc);
-		assertThat(asciidoc).hasToString("|[[my.spring.test.prop]]<<my.spring.test.prop,`+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 @@ void descriptionWithPipe() {
 		SingleRow row = new SingleRow(SNIPPET, property);
 		Asciidoc asciidoc = new Asciidoc();
 		row.write(asciidoc);
-		assertThat(asciidoc).hasToString("|[[my.spring.test.prop]]<<my.spring.test.prop,`+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 @@ void mapProperty() {
 		SingleRow row = new SingleRow(SNIPPET, property);
 		Asciidoc asciidoc = new Asciidoc();
 		row.write(asciidoc);
-		assertThat(asciidoc).hasToString("|[[my.spring.test.prop]]<<my.spring.test.prop,`+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 @@ void listProperty() {
 		SingleRow row = new SingleRow(SNIPPET, property);
 		Asciidoc asciidoc = new Asciidoc();
 		row.write(asciidoc);
-		assertThat(asciidoc).hasToString("|[[my.spring.test.prop]]<<my.spring.test.prop,`+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);
 	}

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 @@
  * Tests for {@link Table}.
  *
  * @author Brian Clozel
+ * @author Moritz Halbritter
  */
 class TableTests {
 
@@ -44,10 +45,10 @@ void simpleTable() {
 		assertThat(asciidoc).hasToString("[cols=\"4,3,3\", options=\"header\"]" + NEWLINE +
 		"|===" + NEWLINE +
 		"|Name|Description|Default Value" + NEWLINE + NEWLINE +
-		"|[[my.spring.test.other]]<<my.spring.test.other,`+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]]<<my.spring.test.prop,`+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);

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:
 
-* <<overview.endpoint-urls>>
-* <<overview.timestamps>>
+* xref:#overview.endpoint-urls[]
+* xref:#overview.timestamps[]
 
 NOTE: In order to get the correct JSON responses documented below, Jackson must be available.
 

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 <<packaging.repackage-goal.parameter-details.layout-factory,layout>> is set.
+Layout factories are always ignored if an explicit xref:#packaging.repackage-goal.parameter-details.layout-factory[layout] is set.
 
 
 

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 `<version>` tags for those dependencies when used in your own POM.
-* An execution of the <<goals.adoc#packaging.repackage-goal, `repackage` goal>> 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]).