Skip to content

Commit 1a8a69d

Browse files
bclozelbclozel
committed
Refactor Asciidoctor attributes in reference docs
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.
1 parent e16cdfe commit 1a8a69d

21 files changed

+56
-62
lines changed

Diff for: ‎framework-docs/framework-docs.gradle

+1-7
Original file line numberDiff line numberDiff line change
@@ -80,8 +80,6 @@ rootProject.tasks.dokkaHtmlMultiModule.configure {
8080
}
8181

8282
asciidoctorj {
83-
def docRoot = 'https://docs.spring.io'
84-
def docsSpringFramework = "${docRoot}/spring-framework/docs/${project.version}"
8583
version = '2.4.3'
8684
fatalWarnings ".*"
8785
options doctype: 'book', eruby: 'erubis'
@@ -92,11 +90,7 @@ asciidoctorj {
9290
revnumber: project.version,
9391
sectanchors: '',
9492
sectnums: '',
95-
'spring-version': project.version,
96-
'spring-framework-main-code': 'https://github.com/spring-projects/spring-framework/tree/main',
97-
'doc-root': docRoot,
98-
'docs-spring-framework': docsSpringFramework,
99-
'api-spring-framework': "${docsSpringFramework}/javadoc-api/org/springframework"
93+
'spring-version': project.version
10094
])
10195
}
10296

Diff for: ‎framework-docs/src/docs/asciidoc/appendix.adoc

+2-4
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,7 @@
11
[[appendix]]
22
= Appendix
3-
:toc: left
4-
:toclevels: 4
5-
:tabsize: 4
6-
:docinfo1:
3+
include::attributes.adoc[]
4+
include::page-layout.adoc[]
75

86
This part of the reference documentation covers topics that apply to multiple modules
97
within the core Spring Framework.

Diff for: ‎framework-docs/src/docs/asciidoc/attributes.adoc

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
:docs-java: {docdir}/../../main/java/org/springframework/docs
2+
:docs-kotlin: {docdir}/../../main/kotlin/org/springframework/docs
3+
:docs-resources: {docdir}/../../main/resources
4+
:spring-framework-main-code: https://github.com/spring-projects/spring-framework/tree/main
5+
:docs-site: https://docs.spring.io
6+
:docs-spring-framework: {docs-site}/spring-framework/docs/{spring-version}
7+
:api-spring-framework: {docs-spring-framework}/javadoc-api/org/springframework
8+
:doc-spring-amqp: {docs-site}/spring-amqp/docs/current/reference
9+
:doc-spring-gemfire: {docs-site}/spring-gemfire/docs/current/reference
10+
:gh-rsocket: https://github.com/rsocket
11+
:gh-rsocket-java: {gh-rsocket}/rsocket-java
12+
:gh-rsocket-extensions: {gh-rsocket}/rsocket/blob/master/Extensions
13+
:doc-spring-boot: {docs-site}/spring-boot/docs/current/reference

Diff for: ‎framework-docs/src/docs/asciidoc/core.adoc

+2-4
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,7 @@
11
[[spring-core]]
22
= Core Technologies
3-
:toc: left
4-
:toclevels: 4
5-
:tabsize: 4
6-
:docinfo1:
3+
include::attributes.adoc[]
4+
include::page-layout.adoc[]
75

86
This part of the reference documentation covers all the technologies that are
97
absolutely integral to the Spring Framework.

Diff for: ‎framework-docs/src/docs/asciidoc/core/core-aot.adoc

+9-9
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
[[aot]]
1+
[[core.aot]]
22
= Ahead of Time Optimizations
33

44
This chapter covers Spring's Ahead of Time (AOT) optimizations.
@@ -28,7 +28,7 @@ A Spring AOT processed application typically generates:
2828
NOTE: At the moment, AOT is focused on allowing Spring applications to be deployed as native images using GraalVM.
2929
We intend to support more JVM-based use cases in future generations.
3030

31-
[[aot-basics]]
31+
[[core.aot.basics]]
3232
== AOT engine overview
3333

3434
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
4444

4545
Those steps are covered in greater detail in the sections below.
4646

47-
[[aot-refresh]]
47+
[[core.aot.refresh]]
4848
== Refresh for AOT Processing
4949

5050
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.
8888

8989
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.
9090

91-
[[aot-bean-factory-initialization-contributions]]
91+
[[core.aot.bean-factory-initialization-contributions]]
9292
== Bean Factory Initialization AOT Contributions
9393

9494
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
111111
====
112112

113113

114-
[[aot-bean-registration-contributions]]
114+
[[core.aot.bean-registration-contributions]]
115115
=== Bean Registration AOT Contributions
116116

117117
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.
198198
This supplier invokes the `dataSource()` method on the `dataSourceConfiguration` bean.
199199

200200

201-
[[aot-hints]]
201+
[[core.aot.hints]]
202202
== Runtime Hints
203203

204204
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
222222
A number of convenient annotations are also provided for common use cases.
223223

224224

225-
[[aot-hints-import-runtime-hints]]
225+
[[core.aot.hints.import-runtime-hints]]
226226
=== `@ImportRuntimeHints`
227227

228228
`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
254254
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.
255255

256256

257-
[[aot-hints-reflective]]
257+
[[core.aot.hints.reflective]]
258258
=== `@Reflective`
259259

260260
{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.
268268
If components other than Spring beans need to be processed, a `BeanFactoryInitializationAotProcessor` can detect the relevant types and use `ReflectiveRuntimeHintsRegistrar` to process them.
269269

270270

271-
[[aot-hints-register-reflection-for-binding]]
271+
[[core.aot.hints.register-reflection-for-binding]]
272272
=== `@RegisterReflectionForBinding`
273273

274274
{api-spring-framework}/aot/hint/annotation/RegisterReflectionForBinding.html[`@RegisterReflectionForBinding`] is a specialization of `@Reflective` that registers the need for serializing arbitrary types.

Diff for: ‎framework-docs/src/docs/asciidoc/data-access.adoc

+2-4
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,7 @@
11
[[spring-data-tier]]
22
= Data Access
3-
:toc: left
4-
:toclevels: 4
5-
:tabsize: 4
6-
:docinfo1:
3+
include::attributes.adoc[]
4+
include::page-layout.adoc[]
75

86
This part of the reference documentation is concerned with data access and the
97
interaction between the data access layer and the business or service layer.

Diff for: ‎framework-docs/src/docs/asciidoc/index.adoc

+1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
:noheader:
22
= Spring Framework Documentation
3+
include::attributes.adoc[]
34

45
[horizontal]
56
<<overview.adoc#overview, Overview>> :: history, design philosophy, feedback,

Diff for: ‎framework-docs/src/docs/asciidoc/integration.adoc

+2-6
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,7 @@
11
[[spring-integration]]
22
= Integration
3-
:doc-spring-amqp: {doc-root}/spring-amqp/docs/current/reference
4-
:doc-spring-gemfire: {doc-root}/spring-gemfire/docs/current/reference
5-
:toc: left
6-
:toclevels: 4
7-
:tabsize: 4
8-
:docinfo1:
3+
include::attributes.adoc[]
4+
include::page-layout.adoc[]
95

106
This part of the reference documentation covers Spring Framework's integration with
117
a number of technologies.

Diff for: ‎framework-docs/src/docs/asciidoc/languages.adoc

+2-4
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,7 @@
11
[[languages]]
22
= Language Support
3-
:toc: left
4-
:toclevels: 4
5-
:tabsize: 4
6-
:docinfo1:
3+
include::attributes.adoc[]
4+
include::page-layout.adoc[]
75

86
include::languages/kotlin.adoc[leveloffset=+1]
97

Diff for: ‎framework-docs/src/docs/asciidoc/overview.adoc

+1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
[[overview]]
22
= Spring Framework Overview
3+
include::attributes.adoc[]
34
:toc: left
45
:toclevels: 1
56
:docinfo1:

Diff for: ‎framework-docs/src/docs/asciidoc/page-layout.adoc

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
:toc: left
2+
:toclevels: 4
3+
:tabsize: 4
4+
:docinfo1:

Diff for: ‎framework-docs/src/docs/asciidoc/rsocket.adoc

+2-3
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,7 @@
11
[[rsocket]]
22
= RSocket
3-
:gh-rsocket: https://github.com/rsocket
4-
:gh-rsocket-java: {gh-rsocket}/rsocket-java
5-
:gh-rsocket-extensions: {gh-rsocket}/rsocket/blob/master/Extensions
3+
include::attributes.adoc[]
4+
include::page-layout.adoc[]
65

76
This section describes Spring Framework's support for the RSocket protocol.
87

Diff for: ‎framework-docs/src/docs/asciidoc/spring-framework.adocbook

+1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
:noheader:
22
= Spring Framework Documentation
3+
include::attributes.adoc[]
34

45
include::overview.adoc[leveloffset=+1]
56
include::core.adoc[leveloffset=+1]

Diff for: ‎framework-docs/src/docs/asciidoc/testing.adoc

+5-8
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,7 @@
11
[[testing]]
22
= Testing
3-
:doc-spring-boot: {doc-root}/spring-boot/docs/current/reference
4-
:toc: left
5-
:toclevels: 4
6-
:tabsize: 4
7-
:docinfo1:
3+
include::attributes.adoc[]
4+
include::page-layout.adoc[]
85

96
This chapter covers Spring's support for integration testing and best practices for unit
107
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
69886985
This chapter covers Spring's Ahead of Time (AOT) support for integration tests using the
69896986
Spring TestContext Framework.
69906987

6991-
The testing support extends Spring's <<core.adoc#aot,core AOT support>> with the
6988+
The testing support extends Spring's <<core.adoc#core.aot,core AOT support>> with the
69926989
following features.
69936990

69946991
* Build-time detection of all integration tests in the current project that use the
@@ -6998,7 +6995,7 @@ following features.
69986995
testing annotations -- as long as the tests are run using a JUnit Platform
69996996
`TestEngine` that is registered for the current project.
70006997
* Build-time AOT processing: each unique test `ApplicationContext` in the current project
7001-
will be <<core.adoc#aot-refresh,refreshed for AOT processing>>.
6998+
will be <<core.adoc#core.aot.refresh,refreshed for AOT processing>>.
70026999
* Runtime AOT support: when executing in AOT runtime mode, a Spring integration test will
70037000
use an AOT-optimized `ApplicationContext` that participates transparently with the
70047001
<<testcontext-ctx-management-caching, context cache>>.
@@ -7019,7 +7016,7 @@ the following options.
70197016
via {api-spring-framework}/context/annotation/ImportRuntimeHints.html[`@ImportRuntimeHints`].
70207017
* Annotate a test class with {api-spring-framework}/aot/hint/annotation/Reflective.html[`@Reflective`] or
70217018
{api-spring-framework}/aot/hint/annotation/RegisterReflectionForBinding.html[`@RegisterReflectionForBinding`].
7022-
* See <<core.adoc#aot-hints,Runtime Hints>> for details on Spring's core runtime hints
7019+
* See <<core.adoc#core.aot.hints,Runtime Hints>> for details on Spring's core runtime hints
70237020
and annotation support.
70247021

70257022
[TIP]

Diff for: ‎framework-docs/src/docs/asciidoc/web-reactive.adoc

+2-4
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,7 @@
11
[[spring-web-reactive]]
22
= Web on Reactive Stack
3-
:toc: left
4-
:toclevels: 4
5-
:tabsize: 4
6-
:docinfo1:
3+
include::attributes.adoc[]
4+
include::page-layout.adoc[]
75

86
This part of the documentation covers support for reactive-stack web applications built
97
on a https://www.reactive-streams.org/[Reactive Streams] API to run on non-blocking

Diff for: ‎framework-docs/src/docs/asciidoc/web.adoc

+2-4
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,7 @@
11
[[spring-web]]
22
= Web on Servlet Stack
3-
:toc: left
4-
:toclevels: 4
5-
:tabsize: 4
6-
:docinfo1:
3+
include::attributes.adoc[]
4+
include::page-layout.adoc[]
75

86
This part of the documentation covers support for Servlet-stack web applications built on the
97
Servlet API and deployed to Servlet containers. Individual chapters include <<mvc, Spring MVC>>,

Diff for: ‎framework-docs/src/docs/asciidoc/web/webflux-cors.adoc

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[[webflux-cors]]
22
= CORS
3-
:doc-spring-security: {doc-root}/spring-security/reference
3+
:doc-spring-security: {docs-site}/spring-security/reference
44
[.small]#<<web.adoc#mvc-cors, Web MVC>>#
55

66
Spring WebFlux lets you handle CORS (Cross-Origin Resource Sharing). This section

Diff for: ‎framework-docs/src/docs/asciidoc/web/webflux.adoc

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
[[webflux]]
22
:chapter: webflux
33
= Spring WebFlux
4-
:doc-spring-security: {doc-root}/spring-security/reference
4+
:doc-spring-security: {docs-site}/spring-security/reference
55

66
The original web framework included in the Spring Framework, Spring Web MVC, was
77
purpose-built for the Servlet API and Servlet containers. The reactive-stack web framework,

Diff for: ‎framework-docs/src/docs/asciidoc/web/webmvc-cors.adoc

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[[mvc-cors]]
22
= CORS
3-
:doc-spring-security: {doc-root}/spring-security/reference
3+
:doc-spring-security: {docs-site}/spring-security/reference
44
[.small]#<<web-reactive.adoc#webflux-cors, WebFlux>>#
55

66
Spring MVC lets you handle CORS (Cross-Origin Resource Sharing). This section

Diff for: ‎framework-docs/src/docs/asciidoc/web/webmvc.adoc

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
[[mvc]]
22
:chapter: mvc
33
= Spring Web MVC
4-
:doc-spring-security: {doc-root}/spring-security/reference
4+
:doc-spring-security: {docs-site}/spring-security/reference
55

66
Spring Web MVC is the original web framework built on the Servlet API and has been included
77
in the Spring Framework from the very beginning. The formal name, "`Spring Web MVC,`"

Diff for: ‎framework-docs/src/docs/asciidoc/web/websocket.adoc

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[[websocket]]
22
= WebSockets
3-
:doc-spring-security: {doc-root}/spring-security/reference
3+
:doc-spring-security: {docs-site}/spring-security/reference
44
[.small]#<<web-reactive.adoc#webflux-websocket, WebFlux>>#
55

66
This part of the reference documentation covers support for Servlet stack, WebSocket

0 commit comments

Comments
 (0)