Skip to content

Commit fec5397

Browse files
wilkinsonawilkinsona
committed
Auto-generate tables describing the first-party starters
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
1 parent 2b64954 commit fec5397

File tree

55 files changed

+280
-205
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

55 files changed

+280
-205
lines changed

‎spring-boot-docs/pom.xml

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,12 @@
3939
<groupId>org.springframework.boot</groupId>
4040
<artifactId>spring-boot-loader-tools</artifactId>
4141
</dependency>
42+
<dependency>
43+
<groupId>org.springframework.boot</groupId>
44+
<artifactId>spring-boot-starters</artifactId>
45+
<type>pom</type>
46+
<version>${project.version}</version>
47+
</dependency>
4248
<!-- Optional deps required when generating Javadoc with Java 8 -->
4349
<dependency>
4450
<groupId>ch.qos.logback</groupId>
@@ -609,6 +615,26 @@
609615
<groupId>org.apache.maven.plugins</groupId>
610616
<artifactId>maven-dependency-plugin</artifactId>
611617
<executions>
618+
<execution>
619+
<id>copy-starters-pom</id>
620+
<phase>generate-resources</phase>
621+
<goals>
622+
<goal>copy</goal>
623+
</goals>
624+
<configuration>
625+
<artifactItems>
626+
<artifactItem>
627+
<groupId>org.springframework.boot</groupId>
628+
<artifactId>spring-boot-starters</artifactId>
629+
<version>${project.version}</version>
630+
<type>pom</type>
631+
<overWrite>true</overWrite>
632+
<outputDirectory>${project.build.directory}/external-resources</outputDirectory>
633+
<destFileName>starters-effective-pom.xml</destFileName>
634+
</artifactItem>
635+
</artifactItems>
636+
</configuration>
637+
</execution>
612638
<execution>
613639
<id>unpack-maven-plugin</id>
614640
<phase>generate-resources</phase>
@@ -680,6 +706,25 @@
680706
</artifactItems>
681707
</configuration>
682708
</execution>
709+
<execution>
710+
<id>unpack-starter-poms</id>
711+
<phase>generate-resources</phase>
712+
<goals>
713+
<goal>unpack</goal>
714+
</goals>
715+
<configuration>
716+
<artifactItems>
717+
<artifactItem>
718+
<groupId>org.springframework.boot</groupId>
719+
<artifactId>spring-boot-starters</artifactId>
720+
<version>${project.version}</version>
721+
<type>zip</type>
722+
<classifier>starter-poms</classifier>
723+
<outputDirectory>${project.build.directory}/external-resources/starter-poms</outputDirectory>
724+
</artifactItem>
725+
</artifactItems>
726+
</configuration>
727+
</execution>
683728
</executions>
684729
</plugin>
685730
<plugin>
@@ -697,6 +742,9 @@
697742
<transformationSets>
698743
<transformationSet>
699744
<dir>${project.build.directory}/external-resources</dir>
745+
<includes>
746+
<include>effective-pom.xml</include>
747+
</includes>
700748
<stylesheet>src/main/xslt/dependencyVersions.xsl</stylesheet>
701749
<fileMappers>
702750
<fileMapper implementation="org.codehaus.plexus.components.io.filemappers.FileExtensionMapper">
@@ -722,6 +770,7 @@
722770
<configuration>
723771
<scripts>
724772
<script>file:///${project.basedir}/src/main/groovy/generateAutoConfigurationClassTables.groovy</script>
773+
<script>file:///${project.basedir}/src/main/groovy/generateStarterTables.groovy</script>
725774
</scripts>
726775
</configuration>
727776
<dependencies>

‎spring-boot-docs/src/main/asciidoc/appendix.adoc

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,3 @@ include::appendix-configuration-metadata.adoc[]
66
include::appendix-auto-configuration-classes.adoc[]
77
include::appendix-executable-jar-format.adoc[]
88
include::appendix-dependency-versions.adoc[]
9-

‎spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc

Lines changed: 8 additions & 153 deletions
Original file line numberDiff line numberDiff line change
@@ -375,164 +375,19 @@ The following application starters are provided by Spring Boot under the
375375
`org.springframework.boot` group:
376376

377377
.Spring Boot application starters
378-
|===
379-
| Name | Description
378+
include::../../../target/generated-resources/application-starters.adoc[]
380379

381-
|`spring-boot-starter`
382-
|The core Spring Boot starter, including auto-configuration support, logging and YAML.
380+
In addition to the application starters, the following starters can be used to add
381+
_<<production-ready-featyres.adoc#production-ready, production ready>>_ features:
383382

384-
|`spring-boot-starter-actuator`
385-
|Production ready features to help you monitor and manage your application.
383+
.Spring Boot production starters
384+
include::../../../target/generated-resources/production-starters.adoc[]
386385

387-
|`spring-boot-starter-amqp`
388-
|Support for the "`Advanced Message Queuing Protocol`" via `spring-rabbit`.
389-
390-
|`spring-boot-starter-aop`
391-
|Support for aspect-oriented programming including `spring-aop` and AspectJ.
392-
393-
|`spring-boot-starter-artemis`
394-
|Support for "`Java Message Service API`" via Apache Artemis.
395-
396-
|`spring-boot-starter-batch`
397-
|Support for "`Spring Batch`" including HSQLDB database.
398-
399-
|`spring-boot-starter-cache`
400-
|Support for Spring's Cache abstraction.
401-
402-
|`spring-boot-starter-cloud-connectors`
403-
|Support for "`Spring Cloud Connectors`" which simplifies connecting to services in cloud
404-
platforms like Cloud Foundry and Heroku.
405-
406-
|`spring-boot-starter-data-elasticsearch`
407-
|Support for the Elasticsearch search and analytics engine including
408-
`spring-data-elasticsearch`.
409-
410-
|`spring-boot-starter-data-gemfire`
411-
|Support for the GemFire distributed data store including `spring-data-gemfire`.
412-
413-
|`spring-boot-starter-data-jpa`
414-
|Support for the "`Java Persistence API`" including `spring-data-jpa`, `spring-orm`
415-
and Hibernate.
416-
417-
|`spring-boot-starter-data-mongodb`
418-
|Support for the MongoDB NoSQL Database, including `spring-data-mongodb`.
419-
420-
|`spring-boot-starter-data-redis`
421-
|Support for the REDIS key-value data store, including `spring-data-redis`.
422-
423-
|`spring-boot-starter-data-neo4j`
424-
|Support for the Neo4j Graph Database, including `spring-data-neo4j`.
425-
426-
|`spring-boot-starter-data-rest`
427-
|Support for exposing Spring Data repositories over REST via `spring-data-rest-webmvc`.
428-
429-
|`spring-boot-starter-data-solr`
430-
|Support for the Apache Solr search platform, including `spring-data-solr`.
431-
432-
|`spring-boot-starter-freemarker`
433-
|Support for the FreeMarker templating engine.
434-
435-
|`spring-boot-starter-groovy-templates`
436-
|Support for the Groovy templating engine.
437-
438-
|`spring-boot-starter-hateoas`
439-
|Support for HATEOAS-based RESTful services via `spring-hateoas`.
440-
441-
|`spring-boot-starter-hornetq`
442-
|Support for "`Java Message Service API`" via HornetQ.
443-
444-
|`spring-boot-starter-integration`
445-
|Support for common `spring-integration` modules.
446-
447-
|`spring-boot-starter-jdbc`
448-
|Support for JDBC databases.
449-
450-
|`spring-boot-starter-jersey`
451-
|Support for the Jersey RESTful Web Services framework.
452-
453-
|`spring-boot-starter-jta-atomikos`
454-
|Support for JTA distributed transactions via Atomikos.
455-
456-
|`spring-boot-starter-jta-bitronix`
457-
|Support for JTA distributed transactions via Bitronix.
458-
459-
|`spring-boot-starter-mail`
460-
|Support for `javax.mail`.
461-
462-
|`spring-boot-starter-mobile`
463-
|Support for `spring-mobile`.
464-
465-
|`spring-boot-starter-mustache`
466-
|Support for the Mustache templating engine.
467-
468-
|`spring-boot-starter-security`
469-
|Support for `spring-security`.
470-
471-
|`spring-boot-starter-social-facebook`
472-
|Support for `spring-social-facebook`.
473-
474-
|`spring-boot-starter-social-linkedin`
475-
|Support for `spring-social-linkedin`.
476-
477-
|`spring-boot-starter-social-twitter`
478-
|Support for `spring-social-twitter`.
479-
480-
|`spring-boot-starter-test`
481-
|Support for common test dependencies, including JUnit, Hamcrest and Mockito along with
482-
the `spring-test` module.
483-
484-
|`spring-boot-starter-thymeleaf`
485-
|Support for the Thymeleaf templating engine, including integration with Spring.
486-
487-
|`spring-boot-starter-velocity`
488-
|Support for the Velocity templating engine. Deprecated in 1.4.
489-
490-
|`spring-boot-starter-web`
491-
|Support for full-stack web development, including Tomcat and `spring-webmvc`.
492-
493-
|`spring-boot-starter-websocket`
494-
|Support for WebSocket development.
495-
496-
|`spring-boot-starter-ws`
497-
|Support for Spring Web Services.
498-
|===
499-
500-
In addition to the application starters, the following starters can be used to
501-
add _<<production-ready-features.adoc#production-ready, production ready>>_ features.
502-
503-
.Spring Boot production ready starters
504-
|===
505-
| Name | Description
506-
507-
|`spring-boot-starter-actuator`
508-
|Adds production ready features such as metrics and monitoring.
509-
510-
|`spring-boot-starter-remote-shell`
511-
|Adds remote `ssh` shell support.
512-
|===
513-
514-
Finally, Spring Boot includes some starters that can be used if you want to exclude or
515-
swap specific technical facets.
386+
Finally, Spring Boot also includes some starters that can be used if you want to exclude
387+
or swap specific technical facets:
516388

517389
.Spring Boot technical starters
518-
|===
519-
| Name | Description
520-
521-
|`spring-boot-starter-jetty`
522-
|Imports the Jetty HTTP engine (to be used as an alternative to Tomcat).
523-
524-
|`spring-boot-starter-log4j2`
525-
|Support the Log4J 2 logging framework.
526-
527-
|`spring-boot-starter-logging`
528-
|Import Spring Boot's default logging framework (Logback).
529-
530-
|`spring-boot-starter-tomcat`
531-
|Import Spring Boot's default HTTP engine (Tomcat).
532-
533-
|`spring-boot-starter-undertow`
534-
|Imports the Undertow HTTP engine (to be used as an alternative to Tomcat).
535-
|===
390+
include::../../../target/generated-resources/technical-starters.adoc[]
536391

537392
TIP: For a list of additional community contributed starter POMs, see the
538393
{github-master-code}/spring-boot-starters/README.adoc[README file] in the

‎spring-boot-docs/src/main/groovy/generateStarterTables.groovy

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
import groovy.util.XmlSlurper
2+
3+
def getStarters(File dir) {
4+
def starters = []
5+
new File(project.build.directory, 'external-resources/starter-poms').eachDir { starterDir ->
6+
def pom = new XmlSlurper().parse(new File(starterDir, 'pom.xml'))
7+
def dependencies = getDependencies(pom)
8+
if (isStarter(dependencies)) {
9+
def name = pom.artifactId.text()
10+
starters << [
11+
'name': name,
12+
'description': postProcessDescription(pom.description.text()),
13+
'dependencies': dependencies,
14+
'pomUrl': "{github-code}/spring-boot-starters/$name/pom.xml"
15+
]
16+
}
17+
}
18+
return starters
19+
}
20+
21+
boolean isApplicationStarter(def starter) {
22+
!isTechnicalStarter(starter) && !isProductionStarter(starter)
23+
}
24+
25+
boolean isTechnicalStarter(def starter) {
26+
starter.name != 'spring-boot-starter-test' && !isProductionStarter(starter) &&
27+
starter.dependencies.find {
28+
it.startsWith('org.springframework.boot:spring-boot-starter') } == null
29+
}
30+
31+
boolean isProductionStarter(def starter) {
32+
starter.name in ['spring-boot-starter-actuator', 'spring-boot-starter-remote-shell']
33+
}
34+
35+
boolean isStarter(def dependencies) {
36+
!dependencies.empty
37+
}
38+
39+
def postProcessDescription(String description) {
40+
addStarterCrossLinks(removeExtraWhitespace(description))
41+
}
42+
43+
def removeExtraWhitespace(String input) {
44+
input.replaceAll('\\s+', ' ')
45+
}
46+
47+
def addStarterCrossLinks(String input) {
48+
input.replaceAll('(spring-boot-starter[A-Za-z-]*)', '<<$1,`$1`>>')
49+
}
50+
51+
def addBackTicksIfNecessary(String input) {
52+
if (!input.contains('`')) {
53+
return "`${input}`"
54+
}
55+
input
56+
}
57+
58+
def getDependencies(def pom) {
59+
dependencies = []
60+
pom.dependencies.dependency.each { dependency ->
61+
dependencies << "${dependency.groupId.text()}:${dependency.artifactId.text()}"
62+
}
63+
dependencies
64+
}
65+
66+
def writeTable(String name, def starters) {
67+
new File(project.build.directory, "generated-resources/${name}.adoc").withPrintWriter { writer ->
68+
writer.println '|==='
69+
writer.println '| Name | Description | Pom'
70+
starters.each { starter ->
71+
writer.println ''
72+
writer.println "| [[${starter.name}]]`${starter.name}`"
73+
writer.println "| ${starter.description}"
74+
writer.println "| ${starter.pomUrl}[Pom]"
75+
}
76+
writer.println '|==='
77+
}
78+
}
79+
80+
def starters = getStarters(new File(project.build.directory, 'external-resources/starter-poms'))
81+
writeTable('application-starters', starters.findAll { isApplicationStarter(it) })
82+
writeTable('production-starters', starters.findAll { isProductionStarter(it) })
83+
writeTable('technical-starters', starters.findAll { isTechnicalStarter(it) })

‎spring-boot-starters/pom.xml

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,47 @@
9797
</execution>
9898
</executions>
9999
</plugin>
100+
<plugin>
101+
<artifactId>maven-assembly-plugin</artifactId>
102+
<version>2.6</version>
103+
<inherited>false</inherited>
104+
<executions>
105+
<execution>
106+
<id>assemble-starter-poms</id>
107+
<phase>generate-resources</phase>
108+
<goals>
109+
<goal>single</goal>
110+
</goals>
111+
<configuration>
112+
<descriptors>
113+
<descriptor>src/main/assembly/starter-poms-assembly.xml</descriptor>
114+
</descriptors>
115+
</configuration>
116+
</execution>
117+
</executions>
118+
</plugin>
119+
<!-- <plugin>
120+
<groupId>org.codehaus.mojo</groupId>
121+
<artifactId>build-helper-maven-plugin</artifactId>
122+
<inherited>false</inherited>
123+
<executions>
124+
<execution>
125+
<id>attach-artifacts</id>
126+
<phase>package</phase>
127+
<goals>
128+
<goal>attach-artifact</goal>
129+
</goals>
130+
<configuration>
131+
<artifacts>
132+
<artifact>
133+
<file>${project.build.directory}/spring-boot-starters-${project.version}-poms.zip</file>
134+
<type>starter-poms</type>
135+
</artifact>
136+
</artifacts>
137+
</configuration>
138+
</execution>
139+
</executions>
140+
</plugin> -->
100141
</plugins>
101142
</build>
102143
</project>

0 commit comments

Comments
 (0)