SpringCloud/spring-cloud-build
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Added automated configprops table generation; fixes gh-144

Browse Source
This commit is contained in:
Marcin Grzejszczak
2019-09-06 13:15:50 +02:00
parent 5c21bf991e
commit 941340a588
5 changed files with 217 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
README.adoc
View File

@@ -252,13 +252,17 @@ approach of generating documentation just add these plugins to your `docs` modul
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-resources-plugin</artifactId> <3>
</plugin>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId> <4>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId> <4>
<artifactId>asciidoctor-maven-plugin</artifactId> <5>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-antrun-plugin</artifactId> <5>
<artifactId>maven-antrun-plugin</artifactId> <6>
</plugin>
</plugins>
</build>
@@ -268,11 +272,14 @@ approach of generating documentation just add these plugins to your `docs` modul
<2> This plugin downloads sets up all the git information of the project
<2> This plugin downloads the resources of the `spring-cloud-build-docs` module
<3> This plugin unpacks the resources of the `spring-cloud-build-docs` module
<4> This plugin is required to parse the Asciidoctor documentation
<5> This plugin is required to copy resources into proper final destinations and to generate main README.adoc and to assert that no files use unresolved links
<4> This plugin generates an `adoc` file with all the configuration properties from the classpath
<5> This plugin is required to parse the Asciidoctor documentation
<6> This plugin is required to copy resources into proper final destinations and to generate main README.adoc and to assert that no files use unresolved links
IMPORTANT: The order of plugin declaration is important!
In order for the build to generate the `adoc` file with all your configuration properties, your `docs` module should contain all the dependencies on the classpath, that you would want to scan for configuration properties. The file will be output to `${docsModule}/src/main/asciidoc/configprops.adoc` file.
Spring Cloud Build Docs comes with a set of attributes for asciidoctor that you can reuse.
[source,xml]

74
docs/pom.xml
View File

@@ -17,14 +17,84 @@
<!-- Comma separated list of whitelisted branches -->
<docs.whitelisted.branches>1.2.x,1.3.x,2.0.x,2.1.x</docs.whitelisted.branches>
<main.basedir>${basedir}/..</main.basedir>
<gmavenplus-plugin.version>1.6.1</gmavenplus-plugin.version>
</properties>
<dependencies>
<!-- Script -->
<dependency>
<groupId>commons-logging</groupId>
<artifactId>commons-logging</artifactId>
<version>1.2</version>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-core</artifactId>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>org.codehaus.groovy</groupId>
<artifactId>groovy</artifactId>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>org.codehaus.groovy</groupId>
<artifactId>groovy-xml</artifactId>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>org.codehaus.groovy</groupId>
<artifactId>groovy-nio</artifactId>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>org.codehaus.groovy</groupId>
<artifactId>groovy-json</artifactId>
<scope>compile</scope>
</dependency>
</dependencies>
<build>
<resources>
<resource>
<directory>src/main</directory>
<excludes>
<exclude>groovy/**/*.*</exclude>
</excludes>
</resource>
</resources>
<plugins>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>build-helper-maven-plugin</artifactId>
<version>${build-helper-maven-plugin.version}</version>
<executions>
<execution>
<id>add-source</id>
<phase>generate-sources</phase>
<goals>
<goal>add-source</goal>
</goals>
<configuration>
<sources>
<source>src/main/groovy</source>
</sources>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.codehaus.gmavenplus</groupId>
<artifactId>gmavenplus-plugin</artifactId>
<version>${gmavenplus-plugin.version}</version>
<executions>
<execution>
<goals>
<goal>compile</goal>
<goal>addSources</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<artifactId>maven-deploy-plugin</artifactId>
<version>2.8.2</version>
@@ -48,6 +118,10 @@
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-resources-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>

15
docs/src/main/asciidoc/README.adoc
View File

@@ -68,13 +68,17 @@ approach of generating documentation just add these plugins to your `docs` modul
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-resources-plugin</artifactId> <3>
</plugin>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId> <4>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId> <4>
<artifactId>asciidoctor-maven-plugin</artifactId> <5>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-antrun-plugin</artifactId> <5>
<artifactId>maven-antrun-plugin</artifactId> <6>
</plugin>
</plugins>
</build>
@@ -84,11 +88,14 @@ approach of generating documentation just add these plugins to your `docs` modul
<2> This plugin downloads sets up all the git information of the project
<2> This plugin downloads the resources of the `spring-cloud-build-docs` module
<3> This plugin unpacks the resources of the `spring-cloud-build-docs` module
<4> This plugin is required to parse the Asciidoctor documentation
<5> This plugin is required to copy resources into proper final destinations and to generate main README.adoc and to assert that no files use unresolved links
<4> This plugin generates an `adoc` file with all the configuration properties from the classpath
<5> This plugin is required to parse the Asciidoctor documentation
<6> This plugin is required to copy resources into proper final destinations and to generate main README.adoc and to assert that no files use unresolved links
IMPORTANT: The order of plugin declaration is important!
In order for the build to generate the `adoc` file with all your configuration properties, your `docs` module should contain all the dependencies on the classpath, that you would want to scan for configuration properties. The file will be output to `${docsModule}/src/main/asciidoc/configprops.adoc` file.
Spring Cloud Build Docs comes with a set of attributes for asciidoctor that you can reuse.
[source,xml]

79
docs/src/main/groovy/org/springframework/cloud/internal/Main.groovy Normal file
View File

@@ -0,0 +1,79 @@
package org.springframework.cloud.internal
import groovy.json.JsonSlurper
import groovy.transform.CompileStatic
import org.springframework.core.io.Resource
import org.springframework.core.io.support.PathMatchingResourcePatternResolver
/**
* @author Marcin Grzejszczak
*/
class Main {
@CompileStatic
static void main(String... args) {
String outputFile = args[0]
new Main().generate(outputFile)
}
void generate(String outputFile) {
println "Parsing all configuration metadata"
Resource[] resources = new PathMatchingResourcePatternResolver()
.getResources("classpath*:/META-INF/spring-configuration-metadata.json")
println "Found [${resources.length}] configuration metadata jsons"
TreeSet names = new TreeSet()
def descriptions = [:]
int count = 0
resources.each { Resource resource ->
if (resource.url.toString().contains("cloud")) {
count++
def slurper = new JsonSlurper()
slurper.parseText(resource.inputStream.text).properties.each { val ->
names.add val.name
descriptions[val.name] = new ConfigValue(val.name, val.description, val.defaultValue)
}
}
}
println "Found [${count}] Cloud projects configuration metadata jsons"
println "Successfully built the description table"
if (names.empty) {
println("Will not update the table, since no configuration properties were found!")
return
}
new File(outputFile).text = """\
|===
|Name | Default | Description
${names.collect { it -> return descriptions[it] }.join("\n")}
|===
"""
println "Successfully stored the output file"
}
@CompileStatic
static class ConfigValue {
String name
String description
Object defaultValue
ConfigValue() {}
ConfigValue(String name, String description, Object defaultValue) {
this.name = name
this.description = escapedValue(description)
this.defaultValue = escapedValue(defaultValue)
}
private String escapedValue(Object value) {
return value != null ?
value.toString().replaceAll('\\|', '\\\\|') : ''
}
String toString() {
"|${name} | ${defaultValue} | ${description}"
}
}
}

46
pom.xml
View File

@@ -940,7 +940,7 @@
</version>
<classifier>sources</classifier>
<type>jar</type>
<overWrite>false</overWrite>
<overWrite>true</overWrite>
<outputDirectory>${docs.resources.dir}
</outputDirectory>
</artifactItem>
@@ -992,6 +992,40 @@
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId>
<version>${exec-maven-plugin.version}</version>
<executions>
<execution>
<id>generate-configprops</id>
<phase>prepare-package</phase>
<goals>
<goal>java</goal>
</goals>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>org.springframework.cloud
</groupId>
<artifactId>spring-cloud-build-docs
</artifactId>
<version>${spring-cloud-build.version}
</version>
<type>jar</type>
</dependency>
</dependencies>
<configuration>
<includePluginDependencies>
true
</includePluginDependencies>
<mainClass>org.springframework.cloud.internal.Main</mainClass>
<arguments>
<argument>${project.basedir}/src/main/asciidoc/configprops.adoc</argument>
</arguments>
</configuration>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
@@ -1039,11 +1073,15 @@
<project-root>${maven.multiModuleProjectDirectory}</project-root>
<!-- It's mandatory for you to pass the docs.main property -->
<github-repo>${docs.main}</github-repo>
<github-raw>https://raw.githubusercontent.com/spring-cloud/${docs.main}/${github-tag}</github-raw>
<github-code>https://github.com/spring-cloud/${docs.main}/tree/${github-tag}</github-code>
<github-raw>
https://raw.githubusercontent.com/spring-cloud/${docs.main}/${github-tag}
</github-raw>
<github-code>https://github.com/spring-cloud/${docs.main}/tree/${github-tag}
</github-code>
<github-issues>https://github.com/spring-cloud/${docs.main}/issues/</github-issues>
<github-wiki>https://github.com/spring-cloud/${docs.main}/wiki</github-wiki>
<github-master-code>https://github.com/spring-cloud/${docs.main}/tree/master</github-master-code>
<github-master-code>https://github.com/spring-cloud/${docs.main}/tree/master
</github-master-code>
<index-link>${index-link}</index-link>
<!-- Spring Cloud specific -->