Auto-generate the "Common application properties"

Prior to this commit, the application properties listed in the reference
documentation would be manually managed and updated.

This commit adds a new `spring-boot-configuration-docs` project that
extracts that information from the available JSON metadata and writes
Asciidoctor tables ready for inclusion in the reference documentation.

The `generateConfigurationPropertyTables.groovy` is using this library
and configures the sections and how namespaces should be organized.

Fixes gh-8237

Author: bclozel

ci/pipeline.yml

@@ -192,6 +192,7 @@ jobs:
       disable_checksum_uploads: true
       exclude:
       - "**/spring-boot-test-support/**"
+      - "**/spring-boot-configuration-docs/**"
       - "**/*.effective-pom"
       artifact_set:
       - include:

spring-boot-project/spring-boot-docs/pom.xml

@@ -55,6 +55,11 @@
 			<groupId>org.springframework.boot</groupId>
 			<artifactId>spring-boot-loader-tools</artifactId>
 		</dependency>
+		<dependency>
+			<groupId>org.springframework.boot</groupId>
+			<artifactId>spring-boot-configuration-docs</artifactId>
+			<version>${revision}</version>
+		</dependency>
 		<dependency>
 			<groupId>org.springframework.boot</groupId>
 			<artifactId>spring-boot-test</artifactId>
@@ -1244,6 +1249,7 @@
 								<script>file:///${project.basedir}/src/main/groovy/generateAutoConfigurationClassTables.groovy</script>
 								<script>file:///${project.basedir}/src/main/groovy/generateStarterTables.groovy</script>
 								<script>file:///${project.basedir}/src/main/groovy/generateTestSlicesTable.groovy</script>
+								<script>file:///${project.basedir}/src/main/groovy/generateConfigurationPropertyTables.groovy</script>
 							</scripts>
 						</configuration>
 						<dependencies>

spring-boot-project/spring-boot-docs/src/main/asciidoc/appendix/application-properties.adoc

@@ -0,0 +1,79 @@
+import org.springframework.boot.configurationdocs.ConfigurationMetadataDocumentWriter
+import org.springframework.boot.configurationdocs.DocumentOptions
+import org.springframework.core.io.UrlResource
+
+import java.nio.file.Path
+import java.nio.file.Paths
+
+def getConfigMetadataInputStreams() {
+	def mainMetadata = getClass().getClassLoader().getResources("META-INF/spring-configuration-metadata.json")
+	def additionalMetadata = getClass().getClassLoader().getResources("META-INF/additional-spring-configuration-metadata.json")
+	def streams = []
+	streams += mainMetadata.collect { new UrlResource(it).getInputStream() }
+	streams += additionalMetadata.collect { new UrlResource(it).getInputStream() }
+	return streams
+}
+
+def generateConfigMetadataDocumentation() {
+
+	def streams = getConfigMetadataInputStreams()
+	try {
+		Path outputPath = Paths.get(project.build.directory, 'generated-resources', 'config-docs')
+		def builder = DocumentOptions.builder();
+
+		builder
+				.addSection("core")
+					.withKeyPrefixes("debug", "trace", "logging", "spring.aop", "spring.application",
+						"spring.autoconfigure", "spring.banner", "spring.beaninfo", "spring.config",
+						"spring.info", "spring.jmx", "spring.main", "spring.messages", "spring.pid",
+						"spring.profiles", "spring.quartz", "spring.reactor", "spring.task",
+						"spring.mandatory-file-encoding", "info", "spring.output.ansi.enabled")
+				.addSection("mail")
+					.withKeyPrefixes("spring.mail", "spring.sendgrid")
+				.addSection("cache")
+					.withKeyPrefixes("spring.cache")
+				.addSection("server")
+					.withKeyPrefixes("server")
+				.addSection("web")
+					.withKeyPrefixes("spring.hateoas",
+						"spring.http", "spring.servlet", "spring.jersey",
+						"spring.mvc", "spring.resources", "spring.webflux")
+				.addSection("json")
+					.withKeyPrefixes("spring.jackson", "spring.gson")
+				.addSection("templating")
+					.withKeyPrefixes("spring.freemarker", "spring.groovy", "spring.mustache", "spring.thymeleaf")
+				.addOverride("spring.groovy.template.configuration", "See GroovyMarkupConfigurer")
+				.addSection("security")
+					.withKeyPrefixes("spring.security", "spring.ldap", "spring.session")
+				.addSection("data-migration")
+					.withKeyPrefixes("spring.flyway", "spring.liquibase")
+				.addSection("data")
+					.withKeyPrefixes("spring.couchbase", "spring.elasticsearch", "spring.h2",
+						"spring.influx", "spring.mongodb", "spring.redis",
+						"spring.dao", "spring.data", "spring.datasource", "spring.jooq",
+						"spring.jdbc", "spring.jpa")
+				.addOverride("spring.datasource.dbcp2", "Commons DBCP2 specific settings")
+				.addOverride("spring.datasource.tomcat", "Tomcat datasource specific settings")
+				.addOverride("spring.datasource.hikari", "Hikari specific settings")
+				.addSection("transaction")
+				.withKeyPrefixes("spring.jta", "spring.transaction")
+				.addSection("integration")
+					.withKeyPrefixes("spring.activemq", "spring.artemis", "spring.batch",
+						"spring.integration", "spring.jms", "spring.kafka", "spring.rabbitmq", "spring.hazelcast",
+						"spring.webservices")
+				.addSection("actuator")
+					.withKeyPrefixes("management")
+				.addSection("devtools")
+					.withKeyPrefixes("spring.devtools")
+				.addSection("testing")
+					.withKeyPrefixes("spring.test");
+
+		ConfigurationMetadataDocumentWriter writer = new ConfigurationMetadataDocumentWriter();
+		writer.writeDocument(outputPath, builder.build(), streams.toArray(new InputStream[0]));
+	}
+	finally {
+		streams.each { it.close() }
+	}
+}
+
+generateConfigMetadataDocumentation()

spring-boot-project/spring-boot-docs/src/main/groovy/generateConfigurationPropertyTables.groovy

@@ -17,6 +17,7 @@
 	<modules>
 		<module>spring-boot-antlib</module>
 		<module>spring-boot-autoconfigure-processor</module>
+		<module>spring-boot-configuration-docs</module>
 		<module>spring-boot-configuration-metadata</module>
 		<module>spring-boot-configuration-processor</module>
 		<module>spring-boot-gradle-plugin</module>

spring-boot-project/spring-boot-tools/pom.xml

@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+	<modelVersion>4.0.0</modelVersion>
+	<parent>
+		<groupId>org.springframework.boot</groupId>
+		<artifactId>spring-boot-tools</artifactId>
+		<version>${revision}</version>
+	</parent>
+	<artifactId>spring-boot-configuration-docs</artifactId>
+	<name>Spring Boot Configuration Docs</name>
+	<description>Spring Boot Configuration Docs</description>
+	<properties>
+		<main.basedir>${basedir}/../../..</main.basedir>
+	</properties>
+	<dependencies>
+		<dependency>
+			<groupId>org.springframework.boot</groupId>
+			<artifactId>spring-boot-configuration-metadata</artifactId>
+		</dependency>
+		<dependency>
+			<groupId>org.springframework.boot</groupId>
+			<artifactId>spring-boot-test-support</artifactId>
+			<scope>test</scope>
+		</dependency>
+	</dependencies>
+</project>

spring-boot-project/spring-boot-tools/spring-boot-configuration-docs/pom.xml

@@ -0,0 +1,61 @@
+/*
+ * Copyright 2012-2019 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.configurationdocs;
+
+import java.util.Objects;
+
+/**
+ * Abstract class for entries in {@link ConfigurationTable}.
+ *
+ * @author Brian Clozel
+ */
+abstract class AbstractConfigurationEntry
+		implements Comparable<AbstractConfigurationEntry> {
+
+	protected static final String NEWLINE = System.lineSeparator();
+
+	protected String key;
+
+	public String getKey() {
+		return this.key;
+	}
+
+	public abstract void writeAsciidoc(StringBuilder builder);
+
+	@Override
+	public boolean equals(Object o) {
+		if (this == o) {
+			return true;
+		}
+		if (o == null || getClass() != o.getClass()) {
+			return false;
+		}
+		AbstractConfigurationEntry that = (AbstractConfigurationEntry) o;
+		return this.key.equals(that.key);
+	}
+
+	@Override
+	public int hashCode() {
+		return Objects.hash(this.key);
+	}
+
+	@Override
+	public int compareTo(AbstractConfigurationEntry other) {
+		return this.key.compareTo(other.getKey());
+	}
+
+}

spring-boot-project/spring-boot-tools/spring-boot-configuration-docs/src/main/java/org/springframework/boot/configurationdocs/AbstractConfigurationEntry.java

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2012-2019 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.configurationdocs;
+
+import java.util.Set;
+import java.util.TreeSet;
+import java.util.stream.Stream;
+
+import org.springframework.boot.configurationmetadata.ConfigurationMetadataProperty;
+
+/**
+ * Table entry regrouping a list of configuration properties sharing the same description.
+ *
+ * @author Brian Clozel
+ */
+class CompoundKeyEntry extends AbstractConfigurationEntry {
+
+	private Set<String> configurationKeys;
+
+	private String description;
+
+	CompoundKeyEntry(String key, String description) {
+		this.key = key;
+		this.description = description;
+		this.configurationKeys = new TreeSet<>();
+	}
+
+	void addConfigurationKeys(ConfigurationMetadataProperty... properties) {
+		Stream.of(properties)
+				.forEach((property) -> this.configurationKeys.add(property.getId()));
+	}
+
+	@Override
+	public void writeAsciidoc(StringBuilder builder) {
+		builder.append("|`+++");
+		this.configurationKeys.forEach((key) -> builder.append(key).append(NEWLINE));
+		builder.append("+++`").append(NEWLINE).append("|").append(NEWLINE).append("|+++")
+				.append(this.description).append("+++").append(NEWLINE);
+	}
+
+}