Restructure spring-boot-docs packages

Restructure the packages in `spring-boot-docs` so that they mirror
the documentation sections. There are now three main packages:
`springbootfeatures`, `productionreadyfeatures` and `howto`. Each
of the main packages has a subpackage named after the section headings.

Example code now uses consistent `// tag::` names and imports are
applied using `[tag=*]` whenever possible.

Test snippets have been moved to `src/main/java` so that only a single
import attribute needs to be defined.

Closes gh-25089

Author: philwebb

spring-boot-project/spring-boot-docs/src/docs/asciidoc/attributes.adoc

@@ -20,8 +20,10 @@
 :github-issues: https://github.com/{github-repo}/issues/
 :github-wiki: https://github.com/{github-repo}/wiki
 
-:code-examples: ../main/java/org/springframework/boot/docs
-:test-examples: ../test/java/org/springframework/boot/docs
+:include: ../main/java/org/springframework/boot/docs
+:include-springbootfeatures: {include}/springbootfeatures
+:include-productionreadyfeatures: {include}/productionreadyfeatures
+:include-howto: {include}/howto
 
 :spring-boot-code: https://github.com/{github-repo}/tree/{github-tag}
 :spring-boot-api: https://docs.spring.io/spring-boot/docs/{spring-boot-version}/api
@@ -94,9 +96,6 @@
 :spring-session: https://spring.io/projects/spring-session
 :spring-webservices-docs: https://docs.spring.io/spring-ws/docs/{spring-webservices-version}/reference/
 
-
-
-
 :ant-docs: https://ant.apache.org/manual
 :dependency-management-plugin-code: https://github.com/spring-gradle-plugins/dependency-management-plugin
 :gradle-docs: https://docs.gradle.org/current/userguide

spring-boot-project/spring-boot-docs/src/docs/asciidoc/howto.adoc

@@ -95,7 +95,7 @@ For instance, the following example loads a YAML configuration file from the cla
 
 [source,java,indent=0]
 ----
-include::{code-examples}/context/EnvironmentPostProcessorExample.java[tag=example]
+include::{include-howto}/springbootapplication/EnvironmentPostProcessorExample.java[tag=*]
 ----
 
 TIP: The `Environment` has already been prepared with all the usual property sources that Spring Boot loads by default.
@@ -931,7 +931,7 @@ You can add an `org.apache.catalina.connector.Connector` to the `TomcatServletWe
 
 [source,java,indent=0,subs="verbatim,quotes,attributes"]
 ----
-include::{code-examples}/context/embedded/TomcatMultipleConnectorsExample.java[tag=configuration]
+include::{include-howto}/embeddedwebservers/TomcatMultipleConnectorsExample.java[tag=*]
 ----
 
 
@@ -951,7 +951,7 @@ To switch to the `LegacyCookieProcessor`, use an `WebServerFactoryCustomizer` be
 
 [source,java,indent=0]
 ----
-include::{code-examples}/context/embedded/TomcatLegacyCookieProcessorExample.java[tag=customizer]
+include::{include-howto}/embeddedwebservers/TomcatLegacyCookieProcessorExample.java[tag=*]
 ----
 
 
@@ -978,7 +978,7 @@ Add an `UndertowBuilderCustomizer` to the `UndertowServletWebServerFactory` and
 
 [source,java,indent=0,subs="verbatim,quotes,attributes"]
 ----
-include::{code-examples}/context/embedded/UndertowMultipleListenersExample.java[tag=configuration]
+include::{include-howto}/embeddedwebservers/UndertowMultipleListenersExample.java[tag=*]
 ----
 
 
@@ -1283,7 +1283,7 @@ The `jersey.config.server.response.setStatusOverSendError` property must be set
 
 [source,java,indent=0]
 ----
-include::{code-examples}/jersey/JerseySetStatusOverSendErrorExample.java[tag=resource-config]
+include::{include-howto}/jersey/JerseySetStatusOverSendErrorExample.java[tag=*]
 ----
 
 
@@ -1326,7 +1326,7 @@ The following example configures `HttpComponentsClientRequestFactory` with an `H
 
 [source,java,indent=0]
 ----
-include::{code-examples}/web/client/RestTemplateProxyCustomizationExample.java[tag=customizer]
+include::{include-springbootfeatures}/resttemplate/RestTemplateProxyCustomizationExample.java[tag=*]
 ----
 
 [[howto-webclient-reactor-netty-customization]]
@@ -1337,7 +1337,7 @@ The following example configures a 60 second connect timeout and adds a `ReadTim
 
 [source,java,indent=0]
 ----
-include::{code-examples}/web/reactive/function/client/ReactorNettyClientCustomizationExample.java[tag=custom-http-connector]
+include::{include-howto}/httpclients/ReactorNettyClientCustomizationExample.java[tag=*]
 ----
 
 TIP: Note the use of `ReactorResourceFactory` for the connection provider and event loop resources.
@@ -1582,7 +1582,7 @@ The following example shows how to create a data source by using a `DataSourceBu
 
 [source,java,indent=0,subs="verbatim,quotes,attributes"]
 ----
-include::{code-examples}/jdbc/BasicDataSourceExample.java[tag=configuration]
+include::{include-howto}/dataaccess/BasicDataSourceExample.java[tag=*]
 ----
 
 To run an app with that `DataSource`, all you need is the connection information.
@@ -1623,7 +1623,7 @@ The following example shows how create a `HikariDataSource` with `DataSourceBuil
 
 [source,java,indent=0,subs="verbatim,quotes,attributes"]
 ----
-include::{code-examples}/jdbc/SimpleDataSourceExample.java[tag=configuration]
+include::{include-howto}/dataaccess/SimpleDataSourceExample.java[tag=*]
 ----
 
 You can even go further by leveraging what `DataSourceProperties` does for you -- that is, by providing a default embedded database with a sensible username and password if no URL is provided.
@@ -1633,7 +1633,7 @@ To avoid that, you can redefine a custom `DataSourceProperties` on your custom n
 
 [source,java,indent=0,subs="verbatim,quotes,attributes"]
 ----
-include::{code-examples}/jdbc/ConfigurableDataSourceExample.java[tag=configuration]
+include::{include-howto}/dataaccess/ConfigurableDataSourceExample.java[tag=*]
 ----
 
 This setup puts you _in sync_ with what Spring Boot does for you by default, except that a dedicated connection pool is chosen (in code) and its settings are exposed in the `app.datasource.configuration` sub namespace.
@@ -1670,7 +1670,7 @@ In the following example, we provide the _exact_ same feature set as the auto-co
 
 [source,java,indent=0,subs="verbatim,quotes,attributes"]
 ----
-include::{code-examples}/jdbc/SimpleTwoDataSourcesExample.java[tag=configuration]
+include::{include-howto}/dataaccess/SimpleTwoDataSourcesExample.java[tag=*]
 ----
 
 TIP: `firstDataSourceProperties` has to be flagged as `@Primary` so that the database initializer feature uses your copy (if you use the initializer).
@@ -1700,7 +1700,7 @@ You can apply the same concept to the secondary `DataSource` as well, as shown i
 
 [source,java,indent=0,subs="verbatim,quotes,attributes"]
 ----
-include::{code-examples}/jdbc/CompleteTwoDataSourcesExample.java[tag=configuration]
+include::{include-howto}/dataaccess/CompleteTwoDataSourcesExample.java[tag=*]
 ----
 
 The preceding example configures two data sources on custom namespaces with the same logic as Spring Boot would use in auto-configuration.
@@ -1794,7 +1794,7 @@ This implementation provides the same table structure as Hibernate 4: all dots a
 
 [source,java,indent=0]
 ----
-include::{code-examples}/jpa/CaseSensitiveSpringPhysicalNamingStrategyExample.java[tag=naming-strategy]
+include::{include-howto}/dataaccess/CaseSensitiveSpringPhysicalNamingStrategyExample.java[tag=*]
 ----
 
 If you prefer to use Hibernate 5's default instead, set the following property:
@@ -1828,7 +1828,7 @@ Then, add a `HibernatePropertiesCustomizer` bean as shown in the following examp
 
 [source,java,indent=0]
 ----
-include::{code-examples}/jpa/HibernateSecondLevelCacheExample.java[tag=configuration]
+include::{include-howto}/dataaccess/HibernateSecondLevelCacheExample.java[tag=*]
 ----
 
 This customizer will configure Hibernate to use the same `CacheManager` as the one that the application uses.
@@ -1969,7 +1969,7 @@ For example, if you use Hibernate Search with Elasticsearch as its index manager
 
 [source,java,indent=0]
 ----
-include::{code-examples}/elasticsearch/HibernateSearchElasticsearchExample.java[tag=configuration]
+include::{include-howto}/dataaccess/HibernateSearchElasticsearchExample.java[tag=*]
 ----
 
 
@@ -2066,7 +2066,7 @@ You can initialize the database on startup using SQL scripts as shown in the fol
 
 [source,java,indent=0]
 ----
-include::{code-examples}/r2dbc/R2dbcDatabaseInitializationExample.java[tag=configuration]
+include::{include-howto}/dataaccess/R2dbcDatabaseInitializationExample.java[tag=*]
 ----
 
 Alternatively, you can configure either <<howto-execute-flyway-database-migrations-on-startup,Flyway>> or <<howto-execute-liquibase-database-migrations-on-startup,Liquibase>> to configure a `DataSource` for you for the duration of the migration.
@@ -2351,7 +2351,7 @@ The following example shows one way to write such an exporter:
 
 [source,java,indent=0,subs="verbatim,quotes,attributes"]
 ----
-include::{code-examples}/actuate/metrics/MetricsHealthMicrometerExportExample.java[tag=configuration]
+include::{include-howto}/actuator/MetricsHealthMicrometerExportExample.java[tag=*]
 ----
 
 

spring-boot-project/spring-boot-docs/src/docs/asciidoc/production-ready-features.adoc

@@ -463,7 +463,7 @@ The following example exposes a read operation that returns a custom object:
 
 [source,java,indent=0]
 ----
-include::{code-examples}/actuate/endpoint/CustomEndpointExample.java[tag=read]
+include::{include-productionreadyfeatures}/endpoints/CustomEndpointExample.java[tag=read]
 ----
 
 You can also write technology-specific endpoints by using `@JmxEndpoint` or `@WebEndpoint`.
@@ -500,7 +500,7 @@ This can be used to invoke a write operation that takes `String name` and `int c
 
 [source,java,indent=0]
 ----
-include::{code-examples}/actuate/endpoint/CustomEndpointExample.java[tag=write]
+include::{include-productionreadyfeatures}/endpoints/CustomEndpointExample.java[tag=write]
 ----
 
 TIP: Because endpoints are technology agnostic, only simple types can be specified in the method signature.
@@ -2379,14 +2379,14 @@ To register custom metrics, inject `MeterRegistry` into your component, as shown
 
 [source,java,indent=0]
 ----
-include::{code-examples}/actuate/metrics/MetricsMeterRegistryInjectionExample.java[tag=component]
+include::{include-productionreadyfeatures}/metrics/MetricsMeterRegistryInjectionExample.java[tag=*]
 ----
 
 If your metrics depend on other beans, it is recommended that you use a `MeterBinder` to register them, as shown in the following example:
 
 [source,java,indent=0]
 ----
-include::{code-examples}/actuate/metrics/SampleMeterBinderConfiguration.java[tag=example]
+include::{include-productionreadyfeatures}/metrics/SampleMeterBinderConfiguration.java[tag=*]
 ----
 
 Using a `MeterBinder` ensures that the correct dependency relationships are set up and that the bean is available when the metric's value is retrieved.
@@ -2404,7 +2404,7 @@ For example, if you want to rename the `mytag.region` tag to `mytag.area` for al
 
 [source,java,indent=0]
 ----
-include::{code-examples}/actuate/metrics/MetricsFilterBeanExample.java[tag=configuration]
+include::{include-productionreadyfeatures}/metrics/MetricsFilterBeanExample.java[tag=*]
 ----
 
 
@@ -2622,7 +2622,7 @@ For Tomcat, the following configuration can be added:
 
 [source,java,indent=0]
 ----
-include::{code-examples}/cloudfoundry/CloudFoundryCustomContextPathExample.java[tag=configuration]
+include::{include-productionreadyfeatures}/cloudfoundry/CloudFoundryCustomContextPathExample.java[tag=*]
 ----