From 68235464fcfe44276906099d8019a1ed8d8db47f Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Tue, 18 Apr 2023 23:09:25 -0500 Subject: [PATCH] Use include-code Macro --- framework-docs/antora-playbook.yml | 1 + framework-docs/antora.yml | 2 +- framework-docs/modules/ROOT/examples/docs-src | 1 + framework-docs/modules/ROOT/pages/core/aot.adoc | 12 ++++++------ .../ROOT/pages/integration/observability.adoc | 10 +++++----- 5 files changed, 14 insertions(+), 12 deletions(-) create mode 120000 framework-docs/modules/ROOT/examples/docs-src diff --git a/framework-docs/antora-playbook.yml b/framework-docs/antora-playbook.yml index ffae717c22..82eec9dc73 100644 --- a/framework-docs/antora-playbook.yml +++ b/framework-docs/antora-playbook.yml @@ -24,6 +24,7 @@ asciidoc: extensions: - '@asciidoctor/tabs' - '@springio/asciidoctor-extensions' + - '@springio/asciidoctor-extensions/include-code-extension' sourcemap: true urls: latest_version_segment: '' diff --git a/framework-docs/antora.yml b/framework-docs/antora.yml index f1ee0f1104..607c9f925f 100644 --- a/framework-docs/antora.yml +++ b/framework-docs/antora.yml @@ -17,7 +17,7 @@ asciidoc: # FIXME: the copyright is not removed # FIXME: The package is not renamed chomp: 'all' - import-java: 'example$docs-src/main/java/org/springframework/docs' + include-java: 'example$docs-src/main/java/org/springframework/docs' spring-framework-main-code: 'https://github.com/spring-projects/spring-framework/tree/main' docs-site: 'https://docs.spring.io' docs-spring: "{docs-site}/spring-framework/docs/{spring-version}" diff --git a/framework-docs/modules/ROOT/examples/docs-src b/framework-docs/modules/ROOT/examples/docs-src new file mode 120000 index 0000000000..dabb0e15a9 --- /dev/null +++ b/framework-docs/modules/ROOT/examples/docs-src @@ -0,0 +1 @@ +../../../src \ No newline at end of file diff --git a/framework-docs/modules/ROOT/pages/core/aot.adoc b/framework-docs/modules/ROOT/pages/core/aot.adoc index 9a1553db5b..14f947fd67 100644 --- a/framework-docs/modules/ROOT/pages/core/aot.adoc +++ b/framework-docs/modules/ROOT/pages/core/aot.adoc @@ -54,13 +54,13 @@ An application context is created with any number of entry points, usually in th Let's look at a basic example: -include::code:AotProcessingSample[tag=myapplication] +include-code::AotProcessingSample[tag=myapplication] Starting this application with the regular runtime involves a number of steps including classpath scanning, configuration class parsing, bean instantiation, and lifecycle callback handling. Refresh for AOT processing only applies a subset of what happens with a xref:core/beans/introduction.adoc[regular `refresh`]. AOT processing can be triggered as follows: -include::code:AotProcessingSample[tag=aotcontext] +include-code::AotProcessingSample[tag=aotcontext] In this mode, xref:core/beans/factory-extension.adoc#beans-factory-extension-factory-postprocessors[`BeanFactoryPostProcessor` implementations] are invoked as usual. This includes configuration class parsing, import selectors, classpath scanning, etc. @@ -217,7 +217,7 @@ A number of convenient annotations are also provided for common use cases. Implementations of this interface can be registered using `@ImportRuntimeHints` on any Spring bean or `@Bean` factory method. `RuntimeHintsRegistrar` implementations are detected and invoked at build time. -include::code:SpellCheckService[] +include-code::SpellCheckService[] If at all possible, `@ImportRuntimeHints` should be used as close as possible to the component that requires the hints. This way, if the component is not contributed to the `BeanFactory`, the hints won't be contributed either. @@ -269,7 +269,7 @@ Spring Core also ships `RuntimeHintsPredicates`, a utility for checking that exi This can be used in your own tests to validate that a `RuntimeHintsRegistrar` contains the expected results. We can write a test for our `SpellCheckService` and ensure that we will be able to load a dictionary at runtime: -include::code:SpellCheckServiceTests[tag=hintspredicates] +include-code::SpellCheckServiceTests[tag=hintspredicates] With `RuntimeHintsPredicates`, we can check for reflection, resource, serialization, or proxy generation hints. This approach works well for unit tests but implies that the runtime behavior of a component is well known. @@ -281,11 +281,11 @@ For more targeted discovery and testing, Spring Framework ships a dedicated modu This module contains the RuntimeHints Agent, a Java agent that records all method invocations that are related to runtime hints and helps you to assert that a given `RuntimeHints` instance covers all recorded invocations. Let's consider a piece of infrastructure for which we'd like to test the hints we're contributing during the AOT processing phase. -include::code:SampleReflection[] +include-code::SampleReflection[] We can then write a unit test (no native compilation required) that checks our contributed hints: -include::code:SampleReflectionRuntimeHintsTests[] +include-code::SampleReflectionRuntimeHintsTests[] If you forgot to contribute a hint, the test will fail and provide some details about the invocation: diff --git a/framework-docs/modules/ROOT/pages/integration/observability.adoc b/framework-docs/modules/ROOT/pages/integration/observability.adoc index b7453decaa..ccb8a6b784 100644 --- a/framework-docs/modules/ROOT/pages/integration/observability.adoc +++ b/framework-docs/modules/ROOT/pages/integration/observability.adoc @@ -66,16 +66,16 @@ Let's take the example of the Spring MVC "http.server.requests" metrics instrume This observation is using a `ServerRequestObservationConvention` with a `ServerRequestObservationContext`; custom conventions can be configured on the Servlet filter. If you would like to customize the metadata produced with the observation, you can extend the `DefaultServerRequestObservationConvention` for your requirements: -include::code:ExtendedServerRequestObservationConvention[] +include-code::ExtendedServerRequestObservationConvention[] If you want full control, you can then implement the entire convention contract for the observation you're interested in: -include::code:CustomServerRequestObservationConvention[] +include-code::CustomServerRequestObservationConvention[] You can also achieve similar goals using a custom `ObservationFilter` - adding or removing key values for an observation. Filters do not replace the default convention and are used as a post-processing component. -include::code:ServerRequestObservationFilter[] +include-code::ServerRequestObservationFilter[] You can configure `ObservationFilter` instances on the `ObservationRegistry`. @@ -95,7 +95,7 @@ This will only record an observation as an error if the `Exception` has not been Typically, all exceptions handled by Spring MVC's `@ExceptionHandler` and xref:web/webmvc/mvc-ann-rest-exceptions.adoc[`ProblemDetail` support] will not be recorded with the observation. You can, at any point during request processing, set the error field on the `ObservationContext` yourself: -include::code:UserController[] +include-code::UserController[] By default, the following `KeyValues` are created: @@ -128,7 +128,7 @@ This will only record an observation as an error if the `Exception` has not been Typically, all exceptions handled by Spring WebFlux's `@ExceptionHandler` and xref:web/webflux/ann-rest-exceptions.adoc[`ProblemDetail` support] will not be recorded with the observation. You can, at any point during request processing, set the error field on the `ObservationContext` yourself: -include::code:UserController[] +include-code::UserController[] By default, the following `KeyValues` are created: