diff --git a/README.adoc b/README.adoc index 716ad88e..fa5bfade 100644 --- a/README.adoc +++ b/README.adoc @@ -252,13 +252,17 @@ approach of generating documentation just add these plugins to your `docs` modul org.apache.maven.plugins maven-resources-plugin <3> + + org.codehaus.mojo + exec-maven-plugin <4> + org.asciidoctor - asciidoctor-maven-plugin <4> + asciidoctor-maven-plugin <5> org.apache.maven.plugins - maven-antrun-plugin <5> + maven-antrun-plugin <6> @@ -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] diff --git a/docs/pom.xml b/docs/pom.xml index 25892558..22a6aebf 100644 --- a/docs/pom.xml +++ b/docs/pom.xml @@ -17,14 +17,84 @@ 1.2.x,1.3.x,2.0.x,2.1.x ${basedir}/.. + 1.6.1 + + + + commons-logging + commons-logging + 1.2 + compile + + + org.springframework + spring-core + compile + + + org.codehaus.groovy + groovy + compile + + + org.codehaus.groovy + groovy-xml + compile + + + org.codehaus.groovy + groovy-nio + compile + + + org.codehaus.groovy + groovy-json + compile + + src/main + + groovy/**/*.* + + + org.codehaus.mojo + build-helper-maven-plugin + ${build-helper-maven-plugin.version} + + + add-source + generate-sources + + add-source + + + + src/main/groovy + + + + + + + org.codehaus.gmavenplus + gmavenplus-plugin + ${gmavenplus-plugin.version} + + + + compile + addSources + + + + maven-deploy-plugin 2.8.2 @@ -48,6 +118,10 @@ org.apache.maven.plugins maven-resources-plugin + + org.codehaus.mojo + exec-maven-plugin + org.asciidoctor asciidoctor-maven-plugin diff --git a/docs/src/main/asciidoc/README.adoc b/docs/src/main/asciidoc/README.adoc index bcaeff33..a2f94a4d 100644 --- a/docs/src/main/asciidoc/README.adoc +++ b/docs/src/main/asciidoc/README.adoc @@ -68,13 +68,17 @@ approach of generating documentation just add these plugins to your `docs` modul org.apache.maven.plugins maven-resources-plugin <3> + + org.codehaus.mojo + exec-maven-plugin <4> + org.asciidoctor - asciidoctor-maven-plugin <4> + asciidoctor-maven-plugin <5> org.apache.maven.plugins - maven-antrun-plugin <5> + maven-antrun-plugin <6> @@ -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] diff --git a/docs/src/main/groovy/org/springframework/cloud/internal/Main.groovy b/docs/src/main/groovy/org/springframework/cloud/internal/Main.groovy new file mode 100644 index 00000000..2d4588f3 --- /dev/null +++ b/docs/src/main/groovy/org/springframework/cloud/internal/Main.groovy @@ -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}" + } + } +} diff --git a/pom.xml b/pom.xml index b78d159c..3723fb94 100644 --- a/pom.xml +++ b/pom.xml @@ -940,7 +940,7 @@ sources jar - false + true ${docs.resources.dir} @@ -992,6 +992,40 @@ + + org.codehaus.mojo + exec-maven-plugin + ${exec-maven-plugin.version} + + + generate-configprops + prepare-package + + java + + + + + + org.springframework.cloud + + spring-cloud-build-docs + + ${spring-cloud-build.version} + + jar + + + + + true + + org.springframework.cloud.internal.Main + + ${project.basedir}/src/main/asciidoc/configprops.adoc + + + org.asciidoctor asciidoctor-maven-plugin @@ -1039,11 +1073,15 @@ ${maven.multiModuleProjectDirectory} ${docs.main} - https://raw.githubusercontent.com/spring-cloud/${docs.main}/${github-tag} - https://github.com/spring-cloud/${docs.main}/tree/${github-tag} + + https://raw.githubusercontent.com/spring-cloud/${docs.main}/${github-tag} + + https://github.com/spring-cloud/${docs.main}/tree/${github-tag} + https://github.com/spring-cloud/${docs.main}/issues/ https://github.com/spring-cloud/${docs.main}/wiki - https://github.com/spring-cloud/${docs.main}/tree/master + https://github.com/spring-cloud/${docs.main}/tree/master + ${index-link}