Refactor Asciidoctor attributes in reference docs

bclozel · bclozel · commit 1a8a69d28981 · 2022-11-17T15:35:28.000+01:00
This commit reorganizes the asciidoctor attributes for the reference
documentation. Instead of being contributed partially by the build and
individual documents, attributes are now shared in common files that are
included in top sections.
diff --git a/framework-docs/framework-docs.gradle b/framework-docs/framework-docs.gradle
@@ -80,8 +80,6 @@ rootProject.tasks.dokkaHtmlMultiModule.configure {
 }
 
 asciidoctorj {
-	def docRoot = 'https://docs.spring.io'
-	def docsSpringFramework = "${docRoot}/spring-framework/docs/${project.version}"
 	version = '2.4.3'
 	fatalWarnings ".*"
 	options doctype: 'book', eruby: 'erubis'
@@ -92,11 +90,7 @@ asciidoctorj {
 			revnumber: project.version,
 			sectanchors: '',
 			sectnums: '',
-			'spring-version': project.version,
-			'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"
+			'spring-version': project.version
 	])
 }
 
diff --git a/framework-docs/src/docs/asciidoc/appendix.adoc b/framework-docs/src/docs/asciidoc/appendix.adoc
@@ -1,9 +1,7 @@
 [[appendix]]
 = Appendix
-:toc: left
-:toclevels: 4
-:tabsize: 4
-:docinfo1:
+include::attributes.adoc[]
+include::page-layout.adoc[]
 
 This part of the reference documentation covers topics that apply to multiple modules
 within the core Spring Framework.
diff --git a/framework-docs/src/docs/asciidoc/attributes.adoc b/framework-docs/src/docs/asciidoc/attributes.adoc
@@ -0,0 +1,13 @@
+:docs-java: {docdir}/../../main/java/org/springframework/docs
+:docs-kotlin: {docdir}/../../main/kotlin/org/springframework/docs
+:docs-resources: {docdir}/../../main/resources
+:spring-framework-main-code: https://github.com/spring-projects/spring-framework/tree/main
+:docs-site: https://docs.spring.io
+:docs-spring-framework: {docs-site}/spring-framework/docs/{spring-version}
+:api-spring-framework: {docs-spring-framework}/javadoc-api/org/springframework
+:doc-spring-amqp: {docs-site}/spring-amqp/docs/current/reference
+:doc-spring-gemfire: {docs-site}/spring-gemfire/docs/current/reference
+:gh-rsocket: https://github.com/rsocket
+:gh-rsocket-java: {gh-rsocket}/rsocket-java
+:gh-rsocket-extensions: {gh-rsocket}/rsocket/blob/master/Extensions
+:doc-spring-boot: {docs-site}/spring-boot/docs/current/reference
diff --git a/framework-docs/src/docs/asciidoc/core.adoc b/framework-docs/src/docs/asciidoc/core.adoc
@@ -1,9 +1,7 @@
 [[spring-core]]
 = Core Technologies
-:toc: left
-:toclevels: 4
-:tabsize: 4
-:docinfo1:
+include::attributes.adoc[]
+include::page-layout.adoc[]
 
 This part of the reference documentation covers all the technologies that are
 absolutely integral to the Spring Framework.
diff --git a/framework-docs/src/docs/asciidoc/core/core-aot.adoc b/framework-docs/src/docs/asciidoc/core/core-aot.adoc
@@ -1,4 +1,4 @@
-[[aot]]
+[[core.aot]]
 = Ahead of Time Optimizations
 
 This chapter covers Spring's Ahead of Time (AOT) optimizations.
@@ -28,7 +28,7 @@ A Spring AOT processed application typically generates:
 NOTE: At the moment, AOT is focused on allowing Spring applications to be deployed as native images using GraalVM.
 We intend to support more JVM-based use cases in future generations.
 
-[[aot-basics]]
+[[core.aot.basics]]
 == AOT engine overview
 
 The entry point of the AOT engine for processing an `ApplicationContext` arrangement is `ApplicationContextAotGenerator`. It takes care of the following steps, based on a `GenericApplicationContext` that represents the application to optimize and a {api-spring-framework}/aot/generate/GenerationContext.html[`GenerationContext`]:
@@ -44,7 +44,7 @@ The `RuntimeHints` instance can also be used to generate the relevant GraalVM na
 
 Those steps are covered in greater detail in the sections below.
 
-[[aot-refresh]]
+[[core.aot.refresh]]
 == Refresh for AOT Processing
 
 Refresh for AOT processing is supported on all `GenericApplicationContext` implementations.
@@ -88,7 +88,7 @@ This makes sure to create any proxy that will be required at runtime.
 
 One this part completes, the `BeanFactory` contains the bean definitions that are necessary for the application to run. It does not trigger bean instantiation but allows the AOT engine to inspect the beans that will be created at runtime.
 
-[[aot-bean-factory-initialization-contributions]]
+[[core.aot.bean-factory-initialization-contributions]]
 == Bean Factory Initialization AOT Contributions
 
 Components that want to participate in this step can implement the {api-spring-framework}/beans/factory/aot/BeanFactoryInitializationAotProcessor.html[`BeanFactoryInitializationAotProcessor`] interface.
@@ -111,7 +111,7 @@ If such a bean is registered using an `@Bean` factory method, ensure the method
 ====
 
 
-[[aot-bean-registration-contributions]]
+[[core.aot.bean-registration-contributions]]
 === Bean Registration AOT Contributions
 
 A core `BeanFactoryInitializationAotProcessor` implementation is responsible for collecting the necessary contributions for each candidate `BeanDefinition`.
@@ -198,7 +198,7 @@ When a `datasource` instance is required, a `BeanInstanceSupplier` is called.
 This supplier invokes the `dataSource()` method on the `dataSourceConfiguration` bean.
 
 
-[[aot-hints]]
+[[core.aot.hints]]
 == Runtime Hints
 
 Running an application as a native image requires additional information compared to a regular JVM runtime.
@@ -222,7 +222,7 @@ For cases that the core container cannot infer, you can register such hints prog
 A number of convenient annotations are also provided for common use cases.
 
 
-[[aot-hints-import-runtime-hints]]
+[[core.aot.hints.import-runtime-hints]]
 === `@ImportRuntimeHints`
 
 `RuntimeHintsRegistrar` implementations allow you to get a callback to the `RuntimeHints` instance managed by the AOT engine.
@@ -254,7 +254,7 @@ This way, if the component is not contributed to the `BeanFactory`, the hints wo
 It is also possible to register an implementation statically by adding an entry in `META-INF/spring/aot.factories` with a key equal to the fully qualified name of the `RuntimeHintsRegistrar` interface.
 
 
-[[aot-hints-reflective]]
+[[core.aot.hints.reflective]]
 === `@Reflective`
 
 {api-spring-framework}/aot/hint/annotation/Reflective.html[`@Reflective`] provides an idiomatic way to flag the need for reflection on an annotated element.
@@ -268,7 +268,7 @@ Library authors can reuse this annotation for their own purposes.
 If components other than Spring beans need to be processed, a `BeanFactoryInitializationAotProcessor` can detect the relevant types and use `ReflectiveRuntimeHintsRegistrar` to process them.
 
 
-[[aot-hints-register-reflection-for-binding]]
+[[core.aot.hints.register-reflection-for-binding]]
 === `@RegisterReflectionForBinding`
 
 {api-spring-framework}/aot/hint/annotation/RegisterReflectionForBinding.html[`@RegisterReflectionForBinding`] is a specialization of `@Reflective` that registers the need for serializing arbitrary types.
diff --git a/framework-docs/src/docs/asciidoc/data-access.adoc b/framework-docs/src/docs/asciidoc/data-access.adoc
@@ -1,9 +1,7 @@
 [[spring-data-tier]]
 = Data Access
-:toc: left
-:toclevels: 4
-:tabsize: 4
-:docinfo1:
+include::attributes.adoc[]
+include::page-layout.adoc[]
 
 This part of the reference documentation is concerned with data access and the
 interaction between the data access layer and the business or service layer.
diff --git a/framework-docs/src/docs/asciidoc/index.adoc b/framework-docs/src/docs/asciidoc/index.adoc
@@ -1,5 +1,6 @@
 :noheader:
 = Spring Framework Documentation
+include::attributes.adoc[]
 
 [horizontal]
 <<overview.adoc#overview, Overview>> :: history, design philosophy, feedback,
diff --git a/framework-docs/src/docs/asciidoc/integration.adoc b/framework-docs/src/docs/asciidoc/integration.adoc
@@ -1,11 +1,7 @@
 [[spring-integration]]
 = Integration
-:doc-spring-amqp: {doc-root}/spring-amqp/docs/current/reference
-:doc-spring-gemfire: {doc-root}/spring-gemfire/docs/current/reference
-:toc: left
-:toclevels: 4
-:tabsize: 4
-:docinfo1:
+include::attributes.adoc[]
+include::page-layout.adoc[]
 
 This part of the reference documentation covers Spring Framework's integration with
 a number of technologies.
diff --git a/framework-docs/src/docs/asciidoc/languages.adoc b/framework-docs/src/docs/asciidoc/languages.adoc
@@ -1,9 +1,7 @@
 [[languages]]
 = Language Support
-:toc: left
-:toclevels: 4
-:tabsize: 4
-:docinfo1:
+include::attributes.adoc[]
+include::page-layout.adoc[]
 
 include::languages/kotlin.adoc[leveloffset=+1]
 
diff --git a/framework-docs/src/docs/asciidoc/overview.adoc b/framework-docs/src/docs/asciidoc/overview.adoc
@@ -1,5 +1,6 @@
 [[overview]]
 = Spring Framework Overview
+include::attributes.adoc[]
 :toc: left
 :toclevels: 1
 :docinfo1:
diff --git a/framework-docs/src/docs/asciidoc/page-layout.adoc b/framework-docs/src/docs/asciidoc/page-layout.adoc
@@ -0,0 +1,4 @@
+:toc: left
+:toclevels: 4
+:tabsize: 4
+:docinfo1:
diff --git a/framework-docs/src/docs/asciidoc/rsocket.adoc b/framework-docs/src/docs/asciidoc/rsocket.adoc
@@ -1,8 +1,7 @@
 [[rsocket]]
 = RSocket
-:gh-rsocket: https://github.com/rsocket
-:gh-rsocket-java: {gh-rsocket}/rsocket-java
-:gh-rsocket-extensions: {gh-rsocket}/rsocket/blob/master/Extensions
+include::attributes.adoc[]
+include::page-layout.adoc[]
 
 This section describes Spring Framework's support for the RSocket protocol.
 
diff --git a/framework-docs/src/docs/asciidoc/spring-framework.adocbook b/framework-docs/src/docs/asciidoc/spring-framework.adocbook
@@ -1,5 +1,6 @@
 :noheader:
 = Spring Framework Documentation
+include::attributes.adoc[]
 
 include::overview.adoc[leveloffset=+1]
 include::core.adoc[leveloffset=+1]
diff --git a/framework-docs/src/docs/asciidoc/testing.adoc b/framework-docs/src/docs/asciidoc/testing.adoc
@@ -1,10 +1,7 @@
 [[testing]]
 = Testing
-:doc-spring-boot: {doc-root}/spring-boot/docs/current/reference
-:toc: left
-:toclevels: 4
-:tabsize: 4
-:docinfo1:
+include::attributes.adoc[]
+include::page-layout.adoc[]
 
 This chapter covers Spring's support for integration testing and best practices for unit
 testing. The Spring team advocates test-driven development (TDD). The Spring team has
@@ -6988,7 +6985,7 @@ of `AbstractTestNGSpringContextTests` for an example of how to instrument your t
 This chapter covers Spring's Ahead of Time (AOT) support for integration tests using the
 Spring TestContext Framework.
 
-The testing support extends Spring's <<core.adoc#aot,core AOT support>> with the
+The testing support extends Spring's <<core.adoc#core.aot,core AOT support>> with the
 following features.
 
 * Build-time detection of all integration tests in the current project that use the
@@ -6998,7 +6995,7 @@ following features.
     testing annotations -- as long as the tests are run using a JUnit Platform
     `TestEngine` that is registered for the current project.
 * Build-time AOT processing: each unique test `ApplicationContext` in the current project
-  will be <<core.adoc#aot-refresh,refreshed for AOT processing>>.
+  will be <<core.adoc#core.aot.refresh,refreshed for AOT processing>>.
 * Runtime AOT support: when executing in AOT runtime mode, a Spring integration test will
   use an AOT-optimized `ApplicationContext` that participates transparently with the
   <<testcontext-ctx-management-caching, context cache>>.
@@ -7019,7 +7016,7 @@ the following options.
   via {api-spring-framework}/context/annotation/ImportRuntimeHints.html[`@ImportRuntimeHints`].
 * Annotate a test class with {api-spring-framework}/aot/hint/annotation/Reflective.html[`@Reflective`] or
   {api-spring-framework}/aot/hint/annotation/RegisterReflectionForBinding.html[`@RegisterReflectionForBinding`].
-* See <<core.adoc#aot-hints,Runtime Hints>> for details on Spring's core runtime hints
+* See <<core.adoc#core.aot.hints,Runtime Hints>> for details on Spring's core runtime hints
   and annotation support.
 
 [TIP]
diff --git a/framework-docs/src/docs/asciidoc/web-reactive.adoc b/framework-docs/src/docs/asciidoc/web-reactive.adoc
@@ -1,9 +1,7 @@
 [[spring-web-reactive]]
 = Web on Reactive Stack
-:toc: left
-:toclevels: 4
-:tabsize: 4
-:docinfo1:
+include::attributes.adoc[]
+include::page-layout.adoc[]
 
 This part of the documentation covers support for reactive-stack web applications built
 on a https://www.reactive-streams.org/[Reactive Streams] API to run on non-blocking
diff --git a/framework-docs/src/docs/asciidoc/web.adoc b/framework-docs/src/docs/asciidoc/web.adoc
@@ -1,9 +1,7 @@
 [[spring-web]]
 = Web on Servlet Stack
-:toc: left
-:toclevels: 4
-:tabsize: 4
-:docinfo1:
+include::attributes.adoc[]
+include::page-layout.adoc[]
 
 This part of the documentation covers support for Servlet-stack web applications built on the
 Servlet API and deployed to Servlet containers. Individual chapters include <<mvc, Spring MVC>>,
diff --git a/framework-docs/src/docs/asciidoc/web/webflux-cors.adoc b/framework-docs/src/docs/asciidoc/web/webflux-cors.adoc
@@ -1,6 +1,6 @@
 [[webflux-cors]]
 = CORS
-:doc-spring-security: {doc-root}/spring-security/reference
+:doc-spring-security: {docs-site}/spring-security/reference
 [.small]#<<web.adoc#mvc-cors, Web MVC>>#
 
 Spring WebFlux lets you handle CORS (Cross-Origin Resource Sharing). This section
diff --git a/framework-docs/src/docs/asciidoc/web/webflux.adoc b/framework-docs/src/docs/asciidoc/web/webflux.adoc
@@ -1,7 +1,7 @@
 [[webflux]]
 :chapter: webflux
 = Spring WebFlux
-:doc-spring-security: {doc-root}/spring-security/reference
+:doc-spring-security: {docs-site}/spring-security/reference
 
 The original web framework included in the Spring Framework, Spring Web MVC, was
 purpose-built for the Servlet API and Servlet containers. The reactive-stack web framework,
diff --git a/framework-docs/src/docs/asciidoc/web/webmvc-cors.adoc b/framework-docs/src/docs/asciidoc/web/webmvc-cors.adoc
@@ -1,6 +1,6 @@
 [[mvc-cors]]
 = CORS
-:doc-spring-security: {doc-root}/spring-security/reference
+:doc-spring-security: {docs-site}/spring-security/reference
 [.small]#<<web-reactive.adoc#webflux-cors, WebFlux>>#
 
 Spring MVC lets you handle CORS (Cross-Origin Resource Sharing). This section
diff --git a/framework-docs/src/docs/asciidoc/web/webmvc.adoc b/framework-docs/src/docs/asciidoc/web/webmvc.adoc
@@ -1,7 +1,7 @@
 [[mvc]]
 :chapter: mvc
 = Spring Web MVC
-:doc-spring-security: {doc-root}/spring-security/reference
+:doc-spring-security: {docs-site}/spring-security/reference
 
 Spring Web MVC is the original web framework built on the Servlet API and has been included
 in the Spring Framework from the very beginning. The formal name, "`Spring Web MVC,`"
diff --git a/framework-docs/src/docs/asciidoc/web/websocket.adoc b/framework-docs/src/docs/asciidoc/web/websocket.adoc
@@ -1,6 +1,6 @@
 [[websocket]]
 = WebSockets
-:doc-spring-security: {doc-root}/spring-security/reference
+:doc-spring-security: {docs-site}/spring-security/reference
 [.small]#<<web-reactive.adoc#webflux-websocket, WebFlux>>#
 
 This part of the reference documentation covers support for Servlet stack, WebSocket
