From 3214786757d34e9f7416057f836af2332e821152 Mon Sep 17 00:00:00 2001 From: Sam Brannen Date: Tue, 22 Jun 2021 18:39:33 +0200 Subject: [PATCH] Define global Asciidoc attributes once This commit defines the doc-root and api-spring-framework attributes once in docs.gradle instead of duplicating them in each *.adoc file. This commit also introduces a new docs-spring-framework global attribute. --- gradle/docs.gradle | 7 ++++++- src/docs/asciidoc/appendix.adoc | 2 -- src/docs/asciidoc/core.adoc | 2 -- src/docs/asciidoc/core/core-appendix.adoc | 3 --- src/docs/asciidoc/data-access.adoc | 2 -- src/docs/asciidoc/index.adoc | 5 ++--- src/docs/asciidoc/integration.adoc | 2 -- src/docs/asciidoc/languages.adoc | 2 -- src/docs/asciidoc/languages/kotlin.adoc | 20 +++++++++---------- src/docs/asciidoc/testing.adoc | 2 -- .../testing/testing-webtestclient.adoc | 2 -- src/docs/asciidoc/web-reactive.adoc | 2 -- src/docs/asciidoc/web.adoc | 2 -- 13 files changed, 18 insertions(+), 35 deletions(-) diff --git a/gradle/docs.gradle b/gradle/docs.gradle index 09d730cf3d..2e1ab520bc 100644 --- a/gradle/docs.gradle +++ b/gradle/docs.gradle @@ -127,6 +127,8 @@ task extractDocResources(type: Copy, dependsOn: downloadResources) { } asciidoctorj { + def docRoot = 'https://docs.spring.io' + def docsSpringFramework = "${docRoot}/spring-framework/docs/${project.version}" version = '2.4.1' fatalWarnings ".*" options doctype: 'book', eruby: 'erubis' @@ -144,7 +146,10 @@ asciidoctorj { stylesdir: 'css/', stylesheet: 'stylesheet.css', 'spring-version': project.version, - 'spring-framework-main-code': 'https://github.com/spring-projects/spring-framework/tree/main' + 'spring-framework-main-code': 'https://github.com/spring-projects/spring-framework/tree/main', + 'doc-root': docRoot, + 'docs-spring-framework': docsSpringFramework, + 'api-spring-framework': "${docsSpringFramework}/javadoc-api/org/springframework" ]) } diff --git a/src/docs/asciidoc/appendix.adoc b/src/docs/asciidoc/appendix.adoc index 4de25e0645..8f11dd941a 100644 --- a/src/docs/asciidoc/appendix.adoc +++ b/src/docs/asciidoc/appendix.adoc @@ -1,7 +1,5 @@ [[appendix]] = Appendix -:doc-root: https://docs.spring.io -:api-spring-framework: {doc-root}/spring-framework/docs/{spring-version}/javadoc-api/org/springframework :toc: left :toclevels: 4 :tabsize: 4 diff --git a/src/docs/asciidoc/core.adoc b/src/docs/asciidoc/core.adoc index b9441028a9..49a9fb3e7d 100644 --- a/src/docs/asciidoc/core.adoc +++ b/src/docs/asciidoc/core.adoc @@ -1,7 +1,5 @@ [[spring-core]] = Core Technologies -:doc-root: https://docs.spring.io -:api-spring-framework: {doc-root}/spring-framework/docs/{spring-version}/javadoc-api/org/springframework :toc: left :toclevels: 4 :tabsize: 4 diff --git a/src/docs/asciidoc/core/core-appendix.adoc b/src/docs/asciidoc/core/core-appendix.adoc index cc5fd0b3d8..53ef8e3335 100644 --- a/src/docs/asciidoc/core/core-appendix.adoc +++ b/src/docs/asciidoc/core/core-appendix.adoc @@ -1,6 +1,3 @@ -:doc-root: https://docs.spring.io -:api-spring-framework: {doc-root}/spring-framework/docs/{spring-version}/javadoc-api/org/springframework - = Appendix diff --git a/src/docs/asciidoc/data-access.adoc b/src/docs/asciidoc/data-access.adoc index 6b61446656..61c8b6330c 100644 --- a/src/docs/asciidoc/data-access.adoc +++ b/src/docs/asciidoc/data-access.adoc @@ -1,7 +1,5 @@ [[spring-data-tier]] = Data Access -:doc-root: https://docs.spring.io -:api-spring-framework: {doc-root}/spring-framework/docs/{spring-version}/javadoc-api/org/springframework :toc: left :toclevels: 4 :tabsize: 4 diff --git a/src/docs/asciidoc/index.adoc b/src/docs/asciidoc/index.adoc index ba0f4c3e87..3df3d0d55e 100644 --- a/src/docs/asciidoc/index.adoc +++ b/src/docs/asciidoc/index.adoc @@ -1,5 +1,4 @@ = Spring Framework Documentation -:doc-root: https://docs.spring.io [horizontal] <> :: history, design philosophy, feedback, @@ -22,11 +21,11 @@ https://github.com/spring-projects/spring-framework/wiki[*Wiki*] :: What's New, and other cross-version information. ifdef::backend-html5[] -NOTE: This documentation is also available as {doc-root}/spring-framework/docs/{spring-version}/reference/pdf/index.pdf[PDF]. +NOTE: This documentation is also available as {docs-spring-framework}/reference/pdf/index.pdf[PDF]. endif::[] ifdef::backend-pdf[] -NOTE: This documentation is also available as {doc-root}/spring-framework/docs/{spring-version}/reference/html/index.html[HTML]. +NOTE: This documentation is also available as {docs-spring-framework}/reference/html/index.html[HTML]. endif::[] Rod Johnson, Juergen Hoeller, Keith Donald, Colin Sampaleanu, Rob Harrop, Thomas Risberg, diff --git a/src/docs/asciidoc/integration.adoc b/src/docs/asciidoc/integration.adoc index 313a1d5026..9e55960525 100644 --- a/src/docs/asciidoc/integration.adoc +++ b/src/docs/asciidoc/integration.adoc @@ -1,7 +1,5 @@ [[spring-integration]] = Integration -:doc-root: https://docs.spring.io -:api-spring-framework: {doc-root}/spring-framework/docs/{spring-version}/javadoc-api/org/springframework :doc-spring-amqp: {doc-root}/spring-amqp/docs/current/reference :doc-spring-gemfire: {doc-root}/spring-gemfire/docs/current/reference :toc: left diff --git a/src/docs/asciidoc/languages.adoc b/src/docs/asciidoc/languages.adoc index 695c5641f8..f47eba7e9c 100644 --- a/src/docs/asciidoc/languages.adoc +++ b/src/docs/asciidoc/languages.adoc @@ -1,7 +1,5 @@ [[languages]] = Language Support -:doc-root: https://docs.spring.io -:api-spring-framework: {doc-root}/spring-framework/docs/{spring-version}/javadoc-api/org/springframework :toc: left :toclevels: 4 :tabsize: 4 diff --git a/src/docs/asciidoc/languages/kotlin.adoc b/src/docs/asciidoc/languages/kotlin.adoc index 7616cc12d5..8b557af245 100644 --- a/src/docs/asciidoc/languages/kotlin.adoc +++ b/src/docs/asciidoc/languages/kotlin.adoc @@ -42,8 +42,8 @@ Kotlin https://kotlinlang.org/docs/reference/extensions.html[extensions] provide to extend existing classes with additional functionality. The Spring Framework Kotlin APIs use these extensions to add new Kotlin-specific conveniences to existing Spring APIs. -The {doc-root}/spring-framework/docs/{spring-version}/kdoc-api/spring-framework/[Spring Framework KDoc API] lists -and documents all available the Kotlin extensions and DSLs. +The {docs-spring-framework}/kdoc-api/spring-framework/[Spring Framework KDoc API] lists +and documents all available Kotlin extensions and DSLs. NOTE: Keep in mind that Kotlin extensions need to be imported to be used. This means, for example, that the `GenericApplicationContext.registerBean` Kotlin extension @@ -209,7 +209,7 @@ the constructor parameters will be autowired by type: ---- In order to allow a more declarative approach and cleaner syntax, Spring Framework provides -a {doc-root}/spring-framework/docs/{spring-version}/kdoc-api/spring-framework/org.springframework.context.support/-bean-definition-dsl/[Kotlin bean definition DSL] +a {docs-spring-framework}/kdoc-api/spring-framework/org.springframework.context.support/-bean-definition-dsl/[Kotlin bean definition DSL] It declares an `ApplicationContextInitializer` through a clean declarative API, which lets you deal with profiles and `Environment` for customizing how beans are registered. @@ -275,9 +275,9 @@ for more details and up-to-date information. See also the experimental Kofu DSL Spring Framework comes with a Kotlin router DSL available in 3 flavors: -* WebMvc.fn DSL with {doc-root}/spring-framework/docs/{spring-version}/kdoc-api/spring-framework/org.springframework.web.servlet.function/router.html[router { }] -* WebFlux.fn <> DSL with {doc-root}/spring-framework/docs/{spring-version}/kdoc-api/spring-framework/org.springframework.web.reactive.function.server/router.html[router { }] -* WebFlux.fn <> DSL with {doc-root}/spring-framework/docs/{spring-version}/kdoc-api/spring-framework/org.springframework.web.reactive.function.server/co-router.html[coRouter { }] +* WebMvc.fn DSL with {docs-spring-framework}/kdoc-api/spring-framework/org.springframework.web.servlet.function/router.html[router { }] +* WebFlux.fn <> DSL with {docs-spring-framework}/kdoc-api/spring-framework/org.springframework.web.reactive.function.server/router.html[router { }] +* WebFlux.fn <> DSL with {docs-spring-framework}/kdoc-api/spring-framework/org.springframework.web.reactive.function.server/co-router.html[coRouter { }] These DSL let you write clean and idiomatic Kotlin code to build a `RouterFunction` instance as the following example shows: @@ -408,10 +408,10 @@ Spring Framework provides support for Coroutines on the following scope: * https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-deferred/index.html[Deferred] and https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html[Flow] return values support in Spring MVC and WebFlux annotated `@Controller` * Suspending function support in Spring MVC and WebFlux annotated `@Controller` -* Extensions for WebFlux {doc-root}/spring-framework/docs/{spring-version}/kdoc-api/spring-framework/org.springframework.web.reactive.function.client/index.html[client] and {doc-root}/spring-framework/docs/{spring-version}/kdoc-api/spring-framework/org.springframework.web.reactive.function.server/index.html[server] functional API. -* WebFlux.fn {doc-root}/spring-framework/docs/{spring-version}/kdoc-api/spring-framework/org.springframework.web.reactive.function.server/co-router.html[coRouter { }] DSL +* Extensions for WebFlux {docs-spring-framework}/kdoc-api/spring-framework/org.springframework.web.reactive.function.client/index.html[client] and {docs-spring-framework}/kdoc-api/spring-framework/org.springframework.web.reactive.function.server/index.html[server] functional API. +* WebFlux.fn {docs-spring-framework}/kdoc-api/spring-framework/org.springframework.web.reactive.function.server/co-router.html[coRouter { }] DSL * Suspending function and `Flow` support in RSocket `@MessageMapping` annotated methods -* Extensions for {doc-root}/spring-framework/docs/{spring-version}/kdoc-api/spring-framework/org.springframework.messaging.rsocket/index.html[`RSocketRequester`] +* Extensions for {docs-spring-framework}/kdoc-api/spring-framework/org.springframework.messaging.rsocket/index.html[`RSocketRequester`] === Dependencies @@ -554,7 +554,7 @@ class CoroutinesViewController(banner: Banner) { === WebFlux.fn -Here is an example of Coroutines router defined via the {doc-root}/spring-framework/docs/{spring-version}/kdoc-api/spring-framework/org.springframework.web.reactive.function.server/co-router.html[coRouter { }] DSL and related handlers. +Here is an example of Coroutines router defined via the {docs-spring-framework}/kdoc-api/spring-framework/org.springframework.web.reactive.function.server/co-router.html[coRouter { }] DSL and related handlers. [source,kotlin,indent=0] ---- diff --git a/src/docs/asciidoc/testing.adoc b/src/docs/asciidoc/testing.adoc index 4516ace078..81455ea5ac 100644 --- a/src/docs/asciidoc/testing.adoc +++ b/src/docs/asciidoc/testing.adoc @@ -1,7 +1,5 @@ [[testing]] = Testing -:doc-root: https://docs.spring.io -:api-spring-framework: {doc-root}/spring-framework/docs/{spring-version}/javadoc-api/org/springframework :doc-spring-boot: {doc-root}/spring-boot/docs/current/reference :toc: left :toclevels: 4 diff --git a/src/docs/asciidoc/testing/testing-webtestclient.adoc b/src/docs/asciidoc/testing/testing-webtestclient.adoc index 09542f2dc5..53a30f4484 100644 --- a/src/docs/asciidoc/testing/testing-webtestclient.adoc +++ b/src/docs/asciidoc/testing/testing-webtestclient.adoc @@ -1,7 +1,5 @@ [[webtestclient]] = WebTestClient -:doc-root: https://docs.spring.io -:api-spring-framework: {doc-root}/spring-framework/docs/{spring-version}/javadoc-api/org/springframework `WebTestClient` is an HTTP client designed for testing server applications. It wraps Spring's <> and uses it to perform requests diff --git a/src/docs/asciidoc/web-reactive.adoc b/src/docs/asciidoc/web-reactive.adoc index f834d54abc..5609f0ba53 100644 --- a/src/docs/asciidoc/web-reactive.adoc +++ b/src/docs/asciidoc/web-reactive.adoc @@ -1,7 +1,5 @@ [[spring-web-reactive]] = Web on Reactive Stack -:doc-root: https://docs.spring.io -:api-spring-framework: {doc-root}/spring-framework/docs/{spring-version}/javadoc-api/org/springframework :toc: left :toclevels: 4 :tabsize: 4 diff --git a/src/docs/asciidoc/web.adoc b/src/docs/asciidoc/web.adoc index aed854cfbb..3aeb445186 100644 --- a/src/docs/asciidoc/web.adoc +++ b/src/docs/asciidoc/web.adoc @@ -1,7 +1,5 @@ [[spring-web]] = Web on Servlet Stack -:doc-root: https://docs.spring.io -:api-spring-framework: {doc-root}/spring-framework/docs/{spring-version}/javadoc-api/org/springframework :toc: left :toclevels: 4 :tabsize: 4