From 0508a9e1f008005ed837e80e38c857315751d3bc Mon Sep 17 00:00:00 2001 From: Tran Ngoc Nhan Date: Sat, 27 Jul 2024 23:00:30 +0700 Subject: [PATCH] Update reference links in HELP.md See gh-1541 --- ...adleBuildSystemHelpDocumentCustomizer.java | 24 +++++++++++++++---- ...avenBuildSystemHelpDocumentCustomizer.java | 16 +++++++++++-- .../GraalVmHelpDocumentCustomizer.java | 20 ++++++++++++---- .../ObservabilityHelpDocumentCustomizer.java | 17 ++++++++++--- .../TestContainersHelpDocumentCustomizer.java | 20 ++++++++++++---- ...uildSystemHelpDocumentCustomizerTests.java | 4 ++-- ...uildSystemHelpDocumentCustomizerTests.java | 6 ++--- .../GraalVmHelpDocumentCustomizerTests.java | 11 +++++++++ 8 files changed, 95 insertions(+), 23 deletions(-) diff --git a/start-site/src/main/java/io/spring/start/site/extension/build/gradle/GradleBuildSystemHelpDocumentCustomizer.java b/start-site/src/main/java/io/spring/start/site/extension/build/gradle/GradleBuildSystemHelpDocumentCustomizer.java index 35052ee14b9..5134c12c687 100644 --- a/start-site/src/main/java/io/spring/start/site/extension/build/gradle/GradleBuildSystemHelpDocumentCustomizer.java +++ b/start-site/src/main/java/io/spring/start/site/extension/build/gradle/GradleBuildSystemHelpDocumentCustomizer.java @@ -20,6 +20,8 @@ import io.spring.initializr.generator.spring.documentation.HelpDocument; import io.spring.initializr.generator.spring.documentation.HelpDocumentCustomizer; import io.spring.initializr.generator.version.Version; +import io.spring.initializr.generator.version.VersionParser; +import io.spring.initializr.generator.version.VersionRange; /** * A {@link HelpDocumentCustomizer} that adds reference links for Gradle. @@ -29,6 +31,10 @@ */ class GradleBuildSystemHelpDocumentCustomizer implements HelpDocumentCustomizer { + private static final String SPRING_BOOT_DOCS_URL = "https://docs.spring.io/spring-boot"; + + private static final VersionRange SPRING_BOOT_3_3_0_OR_LATER = VersionParser.DEFAULT.parseRange("3.3.0"); + private final Version springBootVersion; GradleBuildSystemHelpDocumentCustomizer(ProjectDescription description) { @@ -42,14 +48,22 @@ public void customize(HelpDocument document) { "Gradle Build Scans – insights for your project's build"); document.gettingStarted().addReferenceDocLink("https://docs.gradle.org", "Official Gradle documentation"); document.gettingStarted() - .addReferenceDocLink( - String.format("https://docs.spring.io/spring-boot/docs/%s/gradle-plugin/reference/html/", - this.springBootVersion), - "Spring Boot Gradle Plugin Reference Guide"); + .addReferenceDocLink(generateReferenceGuideUrl(), "Spring Boot Gradle Plugin Reference Guide"); document.gettingStarted() .addReferenceDocLink(String.format( - "https://docs.spring.io/spring-boot/docs/%s/gradle-plugin/reference/html/#build-image", + generateReferenceGuideUrl() + (shouldChangeUrl() ? "/packaging-oci-image.html" : "#build-image"), this.springBootVersion), "Create an OCI image"); } + private String generateReferenceGuideUrl() { + String baseUrlFormat = SPRING_BOOT_DOCS_URL + + (shouldChangeUrl() ? "/%s/gradle-plugin" : "/%s/gradle-plugin/reference/html/"); + return String.format(baseUrlFormat, this.springBootVersion); + } + + private boolean shouldChangeUrl() { + + return this.SPRING_BOOT_3_3_0_OR_LATER.match(this.springBootVersion); + } + } diff --git a/start-site/src/main/java/io/spring/start/site/extension/build/maven/MavenBuildSystemHelpDocumentCustomizer.java b/start-site/src/main/java/io/spring/start/site/extension/build/maven/MavenBuildSystemHelpDocumentCustomizer.java index 3d8ef234871..1333d78b6f5 100644 --- a/start-site/src/main/java/io/spring/start/site/extension/build/maven/MavenBuildSystemHelpDocumentCustomizer.java +++ b/start-site/src/main/java/io/spring/start/site/extension/build/maven/MavenBuildSystemHelpDocumentCustomizer.java @@ -20,6 +20,8 @@ import io.spring.initializr.generator.spring.documentation.HelpDocument; import io.spring.initializr.generator.spring.documentation.HelpDocumentCustomizer; import io.spring.initializr.generator.version.Version; +import io.spring.initializr.generator.version.VersionParser; +import io.spring.initializr.generator.version.VersionRange; /** * A {@link HelpDocumentCustomizer} that adds reference links for Apache Maven. @@ -29,6 +31,10 @@ */ class MavenBuildSystemHelpDocumentCustomizer implements HelpDocumentCustomizer { + private static final String SPRING_BOOT_DOCS_URL = "https://docs.spring.io/spring-boot"; + + private static final VersionRange SPRING_BOOT_3_3_0_OR_LATER = VersionParser.DEFAULT.parseRange("3.3.0"); + private final Version springBootVersion; MavenBuildSystemHelpDocumentCustomizer(ProjectDescription description) { @@ -41,13 +47,19 @@ public void customize(HelpDocument document) { .addReferenceDocLink("https://maven.apache.org/guides/index.html", "Official Apache Maven documentation"); String referenceGuideUrl = generateReferenceGuideUrl(); document.gettingStarted().addReferenceDocLink(referenceGuideUrl, "Spring Boot Maven Plugin Reference Guide"); - String buildImageSection = referenceGuideUrl + "#build-image"; + String buildImageSection = referenceGuideUrl + (shouldChangeUrl() ? "/build-image.html" : "#build-image"); document.gettingStarted().addReferenceDocLink(buildImageSection, "Create an OCI image"); } private String generateReferenceGuideUrl() { - String baseUrlFormat = "https://docs.spring.io/spring-boot/docs/%s/maven-plugin/reference/html/"; + String baseUrlFormat = SPRING_BOOT_DOCS_URL + + (shouldChangeUrl() ? "/%s/maven-plugin" : "/docs/%s/maven-plugin/reference/html/"); return String.format(baseUrlFormat, this.springBootVersion); } + private boolean shouldChangeUrl() { + + return this.SPRING_BOOT_3_3_0_OR_LATER.match(this.springBootVersion); + } + } diff --git a/start-site/src/main/java/io/spring/start/site/extension/dependency/graalvm/GraalVmHelpDocumentCustomizer.java b/start-site/src/main/java/io/spring/start/site/extension/dependency/graalvm/GraalVmHelpDocumentCustomizer.java index 685edb169b7..363f54b6478 100644 --- a/start-site/src/main/java/io/spring/start/site/extension/dependency/graalvm/GraalVmHelpDocumentCustomizer.java +++ b/start-site/src/main/java/io/spring/start/site/extension/dependency/graalvm/GraalVmHelpDocumentCustomizer.java @@ -28,6 +28,8 @@ import io.spring.initializr.generator.spring.documentation.HelpDocument; import io.spring.initializr.generator.spring.documentation.HelpDocumentCustomizer; import io.spring.initializr.generator.version.Version; +import io.spring.initializr.generator.version.VersionParser; +import io.spring.initializr.generator.version.VersionRange; import io.spring.initializr.metadata.Dependency; import io.spring.initializr.metadata.InitializrMetadata; @@ -38,6 +40,8 @@ */ class GraalVmHelpDocumentCustomizer implements HelpDocumentCustomizer { + private static final VersionRange SPRING_BOOT_3_3_0_OR_LATER = VersionParser.DEFAULT.parseRange("3.3.0"); + private final InitializrMetadata metadata; private final ProjectDescription description; @@ -56,13 +60,16 @@ class GraalVmHelpDocumentCustomizer implements HelpDocumentCustomizer { @Override public void customize(HelpDocument document) { document.gettingStarted() - .addReferenceDocLink(String.format( - "https://docs.spring.io/spring-boot/docs/%s/reference/html/native-image.html#native-image", + .addReferenceDocLink(String.format(shouldChangeUrl() + ? "https://docs.spring.io/spring-boot/%s/reference/packaging/native-image/introducing-graalvm-native-images.html" + : "https://docs.spring.io/spring-boot/docs/%s/reference/html/native-image.html#native-image", this.platformVersion), "GraalVM Native Image Support"); boolean mavenBuild = this.build instanceof MavenBuild; boolean gradleBuild = this.build instanceof GradleBuild; - String url = String.format("https://docs.spring.io/spring-boot/docs/%s/%s/reference/htmlsingle/#aot", - this.platformVersion, (mavenBuild) ? "maven-plugin" : "gradle-plugin"); + String url = shouldChangeUrl() + ? String.format("https://docs.spring.io/spring-boot/%s/how-to/aot.html", this.platformVersion) + : String.format("https://docs.spring.io/spring-boot/docs/%s/%s/reference/htmlsingle/#aot", + this.platformVersion, (mavenBuild) ? "maven-plugin" : "gradle-plugin"); document.gettingStarted().addAdditionalLink(url, "Configure AOT settings in Build Plugin"); Map model = new HashMap<>(); @@ -98,4 +105,9 @@ private Stream buildDependencies() { .filter(Objects::nonNull); } + private boolean shouldChangeUrl() { + + return this.SPRING_BOOT_3_3_0_OR_LATER.match(this.platformVersion); + } + } diff --git a/start-site/src/main/java/io/spring/start/site/extension/dependency/observability/ObservabilityHelpDocumentCustomizer.java b/start-site/src/main/java/io/spring/start/site/extension/dependency/observability/ObservabilityHelpDocumentCustomizer.java index a14175982aa..a5af92e7706 100644 --- a/start-site/src/main/java/io/spring/start/site/extension/dependency/observability/ObservabilityHelpDocumentCustomizer.java +++ b/start-site/src/main/java/io/spring/start/site/extension/dependency/observability/ObservabilityHelpDocumentCustomizer.java @@ -21,6 +21,8 @@ import io.spring.initializr.generator.spring.documentation.HelpDocument; import io.spring.initializr.generator.spring.documentation.HelpDocumentCustomizer; import io.spring.initializr.generator.version.Version; +import io.spring.initializr.generator.version.VersionParser; +import io.spring.initializr.generator.version.VersionRange; /** * {@link HelpDocumentCustomizer} implementation for Observability. @@ -29,6 +31,8 @@ */ public class ObservabilityHelpDocumentCustomizer implements HelpDocumentCustomizer { + private static final VersionRange SPRING_BOOT_3_3_0_OR_LATER = VersionParser.DEFAULT.parseRange("3.3.0"); + private final Version platformVersion; private final Build build; @@ -42,13 +46,20 @@ public ObservabilityHelpDocumentCustomizer(ProjectDescription description, Build public void customize(HelpDocument document) { if (this.build.dependencies().has("distributed-tracing")) { document.gettingStarted() - .addReferenceDocLink("https://micrometer.io/docs/tracing", "Distributed Tracing Reference Guide"); + .addReferenceDocLink("https://docs.micrometer.io/tracing/reference/index.html", + "Distributed Tracing Reference Guide"); document.gettingStarted() - .addReferenceDocLink(String.format( - "https://docs.spring.io/spring-boot/docs/%s/reference/html/actuator.html#actuator.micrometer-tracing.getting-started", + .addReferenceDocLink(String.format(shouldChangeUrl() + ? "https://docs.spring.io/spring-boot/%s/reference/actuator/tracing.html" + : "https://docs.spring.io/spring-boot/docs/%s/reference/html/actuator.html#actuator.micrometer-tracing.getting-started", this.platformVersion), "Getting Started with Distributed Tracing"); } } + private boolean shouldChangeUrl() { + + return this.SPRING_BOOT_3_3_0_OR_LATER.match(this.platformVersion); + } + } diff --git a/start-site/src/main/java/io/spring/start/site/extension/dependency/testcontainers/TestContainersHelpDocumentCustomizer.java b/start-site/src/main/java/io/spring/start/site/extension/dependency/testcontainers/TestContainersHelpDocumentCustomizer.java index 91f34224247..41e3d689ce6 100644 --- a/start-site/src/main/java/io/spring/start/site/extension/dependency/testcontainers/TestContainersHelpDocumentCustomizer.java +++ b/start-site/src/main/java/io/spring/start/site/extension/dependency/testcontainers/TestContainersHelpDocumentCustomizer.java @@ -23,6 +23,8 @@ import io.spring.initializr.generator.project.ProjectDescription; import io.spring.initializr.generator.spring.documentation.HelpDocument; import io.spring.initializr.generator.spring.documentation.HelpDocumentCustomizer; +import io.spring.initializr.generator.version.VersionParser; +import io.spring.initializr.generator.version.VersionRange; import io.spring.start.site.container.DockerService; import io.spring.start.site.container.ServiceConnections; import io.spring.start.site.container.ServiceConnections.ServiceConnection; @@ -35,6 +37,8 @@ */ class TestContainersHelpDocumentCustomizer implements HelpDocumentCustomizer { + private static final VersionRange SPRING_BOOT_3_3_0_OR_LATER = VersionParser.DEFAULT.parseRange("3.3.0"); + private final ProjectDescription description; private final ServiceConnections serviceConnections; @@ -46,7 +50,9 @@ class TestContainersHelpDocumentCustomizer implements HelpDocumentCustomizer { @Override public void customize(HelpDocument document) { - String referenceDocUrl = "https://docs.spring.io/spring-boot/docs/%s/reference/html/features.html#features.testing.testcontainers" + String referenceDocUrl = (shouldChangeUrl() + ? "https://docs.spring.io/spring-boot/%s/reference/testing/testcontainers.html#testing.testcontainers" + : "https://docs.spring.io/spring-boot/docs/%s/reference/html/features.html#features.testing.testcontainers") .formatted(this.description.getPlatformVersion()); document.gettingStarted().addReferenceDocLink(referenceDocUrl, "Spring Boot Testcontainers support"); @@ -55,10 +61,16 @@ public void customize(HelpDocument document) { .map(ServiceConnection::dockerService) .toList(); model.put("services", dockerServices); - model.put("testcontainersAtDevelopmentTimeLink", - "https://docs.spring.io/spring-boot/docs/%s/reference/html/features.html#features.testing.testcontainers.at-development-time" - .formatted(this.description.getPlatformVersion())); + model.put("testcontainersAtDevelopmentTimeLink", (shouldChangeUrl() + ? "https://docs.spring.io/spring-boot/%s/reference/features/dev-services.html#features.dev-services.testcontainers" + : "https://docs.spring.io/spring-boot/docs/%s/reference/html/features.html#features.testcontainers") + .formatted(this.description.getPlatformVersion())); document.addSection("testcontainers", model); } + private boolean shouldChangeUrl() { + + return this.SPRING_BOOT_3_3_0_OR_LATER.match(this.description.getPlatformVersion()); + } + } diff --git a/start-site/src/test/java/io/spring/start/site/extension/build/gradle/GradleBuildSystemHelpDocumentCustomizerTests.java b/start-site/src/test/java/io/spring/start/site/extension/build/gradle/GradleBuildSystemHelpDocumentCustomizerTests.java index cefd3029969..74da64eb4d5 100644 --- a/start-site/src/test/java/io/spring/start/site/extension/build/gradle/GradleBuildSystemHelpDocumentCustomizerTests.java +++ b/start-site/src/test/java/io/spring/start/site/extension/build/gradle/GradleBuildSystemHelpDocumentCustomizerTests.java @@ -38,8 +38,8 @@ void linksAddedToHelpDocumentForGradleBuild() { assertHelpDocument("gradle-build", SPRING_BOOT_VERSION).contains( "* [Official Gradle documentation](https://docs.gradle.org)", "* [Gradle Build Scans – insights for your project's build](https://scans.gradle.com#gradle)", - "* [Spring Boot Gradle Plugin Reference Guide](https://docs.spring.io/spring-boot/docs/3.3.0/gradle-plugin/reference/html/)", - "* [Create an OCI image](https://docs.spring.io/spring-boot/docs/3.3.0/gradle-plugin/reference/html/#build-image)"); + "* [Spring Boot Gradle Plugin Reference Guide](https://docs.spring.io/spring-boot/3.3.0/gradle-plugin)", + "* [Create an OCI image](https://docs.spring.io/spring-boot/3.3.0/gradle-plugin/packaging-oci-image.html)"); } @Test diff --git a/start-site/src/test/java/io/spring/start/site/extension/build/maven/MavenBuildSystemHelpDocumentCustomizerTests.java b/start-site/src/test/java/io/spring/start/site/extension/build/maven/MavenBuildSystemHelpDocumentCustomizerTests.java index 56a17532e5c..e4b43e87551 100644 --- a/start-site/src/test/java/io/spring/start/site/extension/build/maven/MavenBuildSystemHelpDocumentCustomizerTests.java +++ b/start-site/src/test/java/io/spring/start/site/extension/build/maven/MavenBuildSystemHelpDocumentCustomizerTests.java @@ -37,15 +37,15 @@ class MavenBuildSystemHelpDocumentCustomizerTests extends AbstractExtensionTests void linksAddedToHelpDocumentForMavenBuild() { assertHelpDocument("maven-build", SPRING_BOOT_VERSION).contains( "* [Official Apache Maven documentation](https://maven.apache.org/guides/index.html)", - "* [Spring Boot Maven Plugin Reference Guide](https://docs.spring.io/spring-boot/docs/3.3.0/maven-plugin/reference/html/)", - "* [Create an OCI image](https://docs.spring.io/spring-boot/docs/3.3.0/maven-plugin/reference/html/#build-image)"); + "* [Spring Boot Maven Plugin Reference Guide](https://docs.spring.io/spring-boot/3.3.0/maven-plugin)", + "* [Create an OCI image](https://docs.spring.io/spring-boot/3.3.0/maven-plugin/build-image.html)"); } @Test void linksNotAddedToHelpDocumentForGradleBuild() { assertHelpDocument("gradle-build", SPRING_BOOT_VERSION).doesNotContain( "* [Official Apache Maven documentation](https://maven.apache.org/guides/index.html)", - "* [Spring Boot Maven Plugin Reference Guide](https://docs.spring.io/spring-boot/docs/3.3.0/maven-plugin/)"); + "* [Spring Boot Maven Plugin Reference Guide](https://docs.spring.io/spring-boot/3.3.0/maven-plugin/)"); } private ListAssert assertHelpDocument(String type, String version) { diff --git a/start-site/src/test/java/io/spring/start/site/extension/dependency/graalvm/GraalVmHelpDocumentCustomizerTests.java b/start-site/src/test/java/io/spring/start/site/extension/dependency/graalvm/GraalVmHelpDocumentCustomizerTests.java index 78961c3b532..b6c4b94200f 100644 --- a/start-site/src/test/java/io/spring/start/site/extension/dependency/graalvm/GraalVmHelpDocumentCustomizerTests.java +++ b/start-site/src/test/java/io/spring/start/site/extension/dependency/graalvm/GraalVmHelpDocumentCustomizerTests.java @@ -45,6 +45,17 @@ class GraalVmHelpDocumentCustomizerTests extends AbstractExtensionTests { @Autowired private MustacheTemplateRenderer templateRenderer; + @Test + void mavenBuildAndGradleAddLinkToMavenAotPlugin() { + MutableProjectDescription description = new MutableProjectDescription(); + description.setPlatformVersion(Version.parse("3.3.0")); + HelpDocument document = customize(description, new MavenBuild()); + assertThat(document.gettingStarted().additionalLinks().getItems()).singleElement().satisfies((link) -> { + assertThat(link.getDescription()).isEqualTo("Configure AOT settings in Build Plugin"); + assertThat(link.getHref()).isEqualTo("https://docs.spring.io/spring-boot/3.3.0/how-to/aot.html"); + }); + } + @Test void mavenBuildAddLinkToMavenAotPlugin() { MutableProjectDescription description = new MutableProjectDescription();