Spring/spring-boot
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Auto-generate tables describing the first-party starters

Browse Source 
Previously, the documentation included hand-written tables for the
application, production, and technical starters.

This commit replaces the hand-written tables with tables that are
generated automatically from all of the starter poms, thereby ensuring
that the documentation is automatically kept up-to-date as starters
are added and removed. An extra column provided a link to each
starter's pom on GitHub has also been added to the table. This makes
it easier for users to see exactly what each starter contains.

Closes gh-5267
This commit is contained in:
Andy Wilkinson
2016-03-29 17:19:29 +01:00
parent 2b649542e0
commit fec53970f7
55 changed files with 280 additions and 205 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
spring-boot-docs/src/main/asciidoc/appendix.adoc
View File

@@ -6,4 +6,3 @@ include::appendix-configuration-metadata.adoc[]
include::appendix-auto-configuration-classes.adoc[]
include::appendix-executable-jar-format.adoc[]
include::appendix-dependency-versions.adoc[]

161
spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc
View File

@@ -375,164 +375,19 @@ The following application starters are provided by Spring Boot under the
`org.springframework.boot` group:
.Spring Boot application starters
|===
| Name | Description
include::../../../target/generated-resources/application-starters.adoc[]
|`spring-boot-starter`
|The core Spring Boot starter, including auto-configuration support, logging and YAML.
In addition to the application starters, the following starters can be used to add
_<<production-ready-featyres.adoc#production-ready, production ready>>_ features:
|`spring-boot-starter-actuator`
|Production ready features to help you monitor and manage your application.
.Spring Boot production starters
include::../../../target/generated-resources/production-starters.adoc[]
|`spring-boot-starter-amqp`
|Support for the "`Advanced Message Queuing Protocol`" via `spring-rabbit`.
|`spring-boot-starter-aop`
|Support for aspect-oriented programming including `spring-aop` and AspectJ.
|`spring-boot-starter-artemis`
|Support for "`Java Message Service API`" via Apache Artemis.
|`spring-boot-starter-batch`
|Support for "`Spring Batch`" including HSQLDB database.
|`spring-boot-starter-cache`
|Support for Spring's Cache abstraction.
|`spring-boot-starter-cloud-connectors`
|Support for "`Spring Cloud Connectors`" which simplifies connecting to services in cloud
platforms like Cloud Foundry and Heroku.
|`spring-boot-starter-data-elasticsearch`
|Support for the Elasticsearch search and analytics engine including
`spring-data-elasticsearch`.
|`spring-boot-starter-data-gemfire`
|Support for the GemFire distributed data store including `spring-data-gemfire`.
|`spring-boot-starter-data-jpa`
|Support for the "`Java Persistence API`" including `spring-data-jpa`, `spring-orm`
and Hibernate.
|`spring-boot-starter-data-mongodb`
|Support for the MongoDB NoSQL Database, including `spring-data-mongodb`.
|`spring-boot-starter-data-redis`
|Support for the REDIS key-value data store, including `spring-data-redis`.
|`spring-boot-starter-data-neo4j`
|Support for the Neo4j Graph Database, including `spring-data-neo4j`.
|`spring-boot-starter-data-rest`
|Support for exposing Spring Data repositories over REST via `spring-data-rest-webmvc`.
|`spring-boot-starter-data-solr`
|Support for the Apache Solr search platform, including `spring-data-solr`.
|`spring-boot-starter-freemarker`
|Support for the FreeMarker templating engine.
|`spring-boot-starter-groovy-templates`
|Support for the Groovy templating engine.
|`spring-boot-starter-hateoas`
|Support for HATEOAS-based RESTful services via `spring-hateoas`.
|`spring-boot-starter-hornetq`
|Support for "`Java Message Service API`" via HornetQ.
|`spring-boot-starter-integration`
|Support for common `spring-integration` modules.
|`spring-boot-starter-jdbc`
|Support for JDBC databases.
|`spring-boot-starter-jersey`
|Support for the Jersey RESTful Web Services framework.
|`spring-boot-starter-jta-atomikos`
|Support for JTA distributed transactions via Atomikos.
|`spring-boot-starter-jta-bitronix`
|Support for JTA distributed transactions via Bitronix.
|`spring-boot-starter-mail`
|Support for `javax.mail`.
|`spring-boot-starter-mobile`
|Support for `spring-mobile`.
|`spring-boot-starter-mustache`
|Support for the Mustache templating engine.
|`spring-boot-starter-security`
|Support for `spring-security`.
|`spring-boot-starter-social-facebook`
|Support for `spring-social-facebook`.
|`spring-boot-starter-social-linkedin`
|Support for `spring-social-linkedin`.
|`spring-boot-starter-social-twitter`
|Support for `spring-social-twitter`.
|`spring-boot-starter-test`
|Support for common test dependencies, including JUnit, Hamcrest and Mockito along with
the `spring-test` module.
|`spring-boot-starter-thymeleaf`
|Support for the Thymeleaf templating engine, including integration with Spring.
|`spring-boot-starter-velocity`
|Support for the Velocity templating engine. Deprecated in 1.4.
|`spring-boot-starter-web`
|Support for full-stack web development, including Tomcat and `spring-webmvc`.
|`spring-boot-starter-websocket`
|Support for WebSocket development.
|`spring-boot-starter-ws`
|Support for Spring Web Services.
|===
In addition to the application starters, the following starters can be used to
add _<<production-ready-features.adoc#production-ready, production ready>>_ features.
.Spring Boot production ready starters
|===
| Name | Description
|`spring-boot-starter-actuator`
|Adds production ready features such as metrics and monitoring.
|`spring-boot-starter-remote-shell`
|Adds remote `ssh` shell support.
|===
Finally, Spring Boot includes some starters that can be used if you want to exclude or
swap specific technical facets.
Finally, Spring Boot also includes some starters that can be used if you want to exclude
or swap specific technical facets:
.Spring Boot technical starters
|===
| Name | Description
|`spring-boot-starter-jetty`
|Imports the Jetty HTTP engine (to be used as an alternative to Tomcat).
|`spring-boot-starter-log4j2`
|Support the Log4J 2 logging framework.
|`spring-boot-starter-logging`
|Import Spring Boot's default logging framework (Logback).
|`spring-boot-starter-tomcat`
|Import Spring Boot's default HTTP engine (Tomcat).
|`spring-boot-starter-undertow`
|Imports the Undertow HTTP engine (to be used as an alternative to Tomcat).
|===
include::../../../target/generated-resources/technical-starters.adoc[]
TIP: For a list of additional community contributed starter POMs, see the
{github-master-code}/spring-boot-starters/README.adoc[README file] in the

83
spring-boot-docs/src/main/groovy/generateStarterTables.groovy Normal file
View File

@@ -0,0 +1,83 @@
import groovy.util.XmlSlurper
def getStarters(File dir) {
def starters = []
new File(project.build.directory, 'external-resources/starter-poms').eachDir { starterDir ->
def pom = new XmlSlurper().parse(new File(starterDir, 'pom.xml'))
def dependencies = getDependencies(pom)
if (isStarter(dependencies)) {
def name = pom.artifactId.text()
starters << [
'name': name,
'description': postProcessDescription(pom.description.text()),
'dependencies': dependencies,
'pomUrl': "{github-code}/spring-boot-starters/$name/pom.xml"
]
}
}
return starters
}
boolean isApplicationStarter(def starter) {
!isTechnicalStarter(starter) && !isProductionStarter(starter)
}
boolean isTechnicalStarter(def starter) {
starter.name != 'spring-boot-starter-test' && !isProductionStarter(starter) &&
starter.dependencies.find {
it.startsWith('org.springframework.boot:spring-boot-starter') } == null
}
boolean isProductionStarter(def starter) {
starter.name in ['spring-boot-starter-actuator', 'spring-boot-starter-remote-shell']
}
boolean isStarter(def dependencies) {
!dependencies.empty
}
def postProcessDescription(String description) {
addStarterCrossLinks(removeExtraWhitespace(description))
}
def removeExtraWhitespace(String input) {
input.replaceAll('\\s+', ' ')
}
def addStarterCrossLinks(String input) {
input.replaceAll('(spring-boot-starter[A-Za-z-]*)', '<<$1,`$1`>>')
}
def addBackTicksIfNecessary(String input) {
if (!input.contains('`')) {
return "`${input}`"
}
input
}
def getDependencies(def pom) {
dependencies = []
pom.dependencies.dependency.each { dependency ->
dependencies << "${dependency.groupId.text()}:${dependency.artifactId.text()}"
}
dependencies
}
def writeTable(String name, def starters) {
new File(project.build.directory, "generated-resources/${name}.adoc").withPrintWriter { writer ->
writer.println '|==='
writer.println '| Name | Description | Pom'
starters.each { starter ->
writer.println ''
writer.println "| [[${starter.name}]]`${starter.name}`"
writer.println "| ${starter.description}"
writer.println "| ${starter.pomUrl}[Pom]"
}
writer.println '|==='
}
}
def starters = getStarters(new File(project.build.directory, 'external-resources/starter-poms'))
writeTable('application-starters', starters.findAll { isApplicationStarter(it) })
writeTable('production-starters', starters.findAll { isProductionStarter(it) })
writeTable('technical-starters', starters.findAll { isTechnicalStarter(it) })