root
/
spring-boot
mirror of https://github.com/spring-projects/spring-boot.git
1
0
Fork 0
Code Issues Actions 9 Packages Projects Releases Wiki Activity

Configure Asciidoctor toolchain for ref docs 

This commit replaces the Docbook+Asciidoctor documentation toolchain by
a single Asciidoctor generation process.

First, we need to unzip the contents of the Spring Asciidoctor
documentation resources provided by the
`io.spring.docsresources:spring-docs-resources` distribution zip. This
is done in a `/target/refdocs` folder. We then copy all files from
`src/main/asciidoc` to the same location, and then launch the generation
process.

Closes gh-12611
This commit is contained in:
Brian Clozel 2018-11-23 21:27:31 +01:00
parent a7d22aaf4b
commit ed3347f00d
3 changed files with 78 additions and 153 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

216
spring-boot-project/spring-boot-docs/pom.xml
View File

@ -13,6 +13,7 @@
<description>Spring Boot Docs</description> <description>Spring Boot Docs</description>
<properties> <properties>
<main.basedir>${basedir}/../..</main.basedir> <main.basedir>${basedir}/../..</main.basedir>
<refdocs.build.directory>${project.build.directory}/refdocs/</refdocs.build.directory>
</properties> </properties>
<dependencies> <dependencies>
<dependency> <dependency>
@ -943,6 +944,14 @@
<artifactId>spring-boot-starter-web</artifactId> <artifactId>spring-boot-starter-web</artifactId>
<scope>test</scope> <scope>test</scope>
</dependency> </dependency>
<!-- Documentation generation -->
<dependency>
<groupId>io.spring.docresources</groupId>
<artifactId>spring-doc-resources</artifactId>
<version>0.1.0-BUILD-SNAPSHOT</version>
<type>zip</type>
<optional>true</optional>
</dependency>
</dependencies> </dependencies>
<build> <build>
<plugins> <plugins>
@ -1150,6 +1159,42 @@
</artifactItems> </artifactItems>
</configuration> </configuration>
</execution> </execution>
<execution>
<id>unpack-doc-resources</id>
<goals>
<goal>unpack-dependencies</goal>
</goals>
<phase>generate-resources</phase>
<configuration>
<includeGroupIds>io.spring.docresources</includeGroupIds>
<includeArtifactIds>spring-doc-resources</includeArtifactIds>
<includeTypes>zip</includeTypes>
<excludeTransitive>true</excludeTransitive>
<outputDirectory>${refdocs.build.directory}</outputDirectory>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-resources-plugin</artifactId>
<executions>
<execution>
<id>copy-asciidoc-resources</id>
<phase>generate-resources</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<outputDirectory>${refdocs.build.directory}</outputDirectory>
<resources>
<resource>
<directory>src/main/asciidoc</directory>
<filtering>false</filtering>
</resource>
</resources>
</configuration>
</execution>
</executions> </executions>
</plugin> </plugin>
<plugin> <plugin>
@ -1221,165 +1266,45 @@
<plugin> <plugin>
<groupId>org.asciidoctor</groupId> <groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId> <artifactId>asciidoctor-maven-plugin</artifactId>
<configuration>
<sourceDirectory>${refdocs.build.directory}</sourceDirectory>
<outputDirectory>${project.build.directory}/generated-docs/reference/html</outputDirectory>
<attributes>
<spring-boot-docs-version>${revision}</spring-boot-docs-version>
<spring-boot-repo>${spring-boot-repo}</spring-boot-repo>
<spring-security-docs-version>${spring-security.version}</spring-security-docs-version>
<spring-webservices-docs-version>${spring-ws.version}</spring-webservices-docs-version>
<github-tag>${github-tag}</github-tag>
<spring-version>${spring.version}</spring-version>
<spring-docs-version>${spring.version}</spring-docs-version>
<spring-boot-version>${revision}</spring-boot-version>
<sources-root>${project.basedir}/src/</sources-root>
</attributes>
</configuration>
<executions> <executions>
<execution> <execution>
<id>generate-docbook</id> <id>generate-html-documentation</id>
<phase>prepare-package</phase> <phase>prepare-package</phase>
<goals> <goals>
<goal>process-asciidoc</goal> <goal>process-asciidoc</goal>
</goals> </goals>
<configuration> <configuration>
<sourceDocumentName>index.adoc</sourceDocumentName> <backend>html5</backend>
<backend>docbook5</backend> <sourceHighlighter>highlight.js</sourceHighlighter>
<doctype>book</doctype> <doctype>book</doctype>
<attributes> <attributes>
<docinfo>true</docinfo> <highlightjsdir>js/highlight</highlightjsdir>
<jooq-version>${jooq.version}</jooq-version> <highlightjs-theme>atom-one-dark-reasonable</highlightjs-theme>
<spring-framework-version>${spring-framework.version}</spring-framework-version> <linkcss>true</linkcss>
<spring-boot-version>${revision}</spring-boot-version> <imagesdir>./images</imagesdir>
<spring-boot-docs-version>${revision}</spring-boot-docs-version> <icons>font</icons>
<spring-boot-repo>${spring-boot-repo}</spring-boot-repo> <stylesdir>css/</stylesdir>
<spring-docs-version>${spring-framework.version}</spring-docs-version> <stylesheet>spring.css</stylesheet>
<spring-security-docs-version>${spring-security.version}</spring-security-docs-version>
<spring-webservices-docs-version>${spring-ws.version}</spring-webservices-docs-version>
<github-tag>${github-tag}</github-tag>
</attributes> </attributes>
</configuration> </configuration>
</execution> </execution>
</executions> </executions>
</plugin> </plugin>
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<version>2.0.17</version>
<configuration>
<sourceDirectory>${basedir}/target/generated-docs</sourceDirectory>
<includes>index.xml</includes>
<xincludeSupported>true</xincludeSupported>
<chunkedOutput>false</chunkedOutput>
<foCustomization>${basedir}/src/main/docbook/xsl/pdf.xsl</foCustomization>
<useExtensions>1</useExtensions>
<highlightSource>1</highlightSource>
<highlightXslthlConfig>${basedir}/src/main/docbook/xsl/xslthl-config.xml</highlightXslthlConfig>
</configuration>
<dependencies>
<dependency>
<groupId>net.sf.xslthl</groupId>
<artifactId>xslthl</artifactId>
<version>2.1.0</version>
</dependency>
<dependency>
<groupId>net.sf.docbook</groupId>
<artifactId>docbook-xml</artifactId>
<version>5.0-all</version>
<classifier>resources</classifier>
<type>zip</type>
<scope>runtime</scope>
</dependency>
</dependencies>
<executions>
<execution>
<id>html-single</id>
<goals>
<goal>generate-html</goal>
</goals>
<phase>prepare-package</phase>
<configuration>
<htmlCustomization>${basedir}/src/main/docbook/xsl/html-singlepage.xsl</htmlCustomization>
<targetDirectory>${basedir}/target/docbook/htmlsingle</targetDirectory>
<postProcess>
<copy todir="${basedir}/target/contents/reference/htmlsingle">
<fileset dir="${basedir}/target/docbook/htmlsingle">
<include name="**/*.html" />
</fileset>
</copy>
<copy todir="${basedir}/target/contents/reference/htmlsingle">
<fileset dir="${basedir}/src/main/docbook">
<include name="**/*.css" />
<include name="**/*.png" />
<include name="**/*.gif" />
<include name="**/*.jpg" />
</fileset>
</copy>
</postProcess>
</configuration>
</execution>
<execution>
<id>html</id>
<goals>
<goal>generate-html</goal>
</goals>
<phase>prepare-package</phase>
<configuration>
<htmlCustomization>${basedir}/src/main/docbook/xsl/html-multipage.xsl</htmlCustomization>
<targetDirectory>${basedir}/target/docbook/html</targetDirectory>
<chunkedOutput>true</chunkedOutput>
<postProcess>
<copy todir="${basedir}/target/contents/reference/html">
<fileset dir="${basedir}/target/docbook/html">
<include name="**/*.html" />
</fileset>
</copy>
<copy todir="${basedir}/target/contents/reference/html">
<fileset dir="${basedir}/src/main/docbook">
<include name="**/*.css" />
<include name="**/*.png" />
<include name="**/*.gif" />
<include name="**/*.jpg" />
</fileset>
</copy>
</postProcess>
</configuration>
</execution>
<execution>
<id>pdf</id>
<goals>
<goal>generate-pdf</goal>
</goals>
<phase>prepare-package</phase>
<configuration>
<foCustomization>${basedir}/src/main/docbook/xsl/pdf.xsl</foCustomization>
<targetDirectory>${basedir}/target/docbook/pdf</targetDirectory>
<postProcess>
<copy todir="${basedir}/target/contents/reference">
<fileset dir="${basedir}/target/docbook">
<include name="**/*.pdf" />
</fileset>
</copy>
<move file="${basedir}/target/contents/reference/pdf/index.pdf"
tofile="${basedir}/target/contents/reference/pdf/spring-boot-reference.pdf" />
</postProcess>
</configuration>
</execution>
<execution>
<id>epub</id>
<goals>
<goal>generate-epub3</goal>
</goals>
<phase>prepare-package</phase>
<configuration>
<epub3Customization>${basedir}/src/main/docbook/xsl/epub.xsl</epub3Customization>
<targetDirectory>${basedir}/target/docbook/epub</targetDirectory>
<preProcess>
<copy todir="${basedir}/target/docbook/epub/images">
<fileset dir="${basedir}/src/main/docbook/images">
<include name="*.png" />
</fileset>
</copy>
</preProcess>
<postProcess>
<copy todir="${basedir}/target/contents/reference/epub">
<fileset dir="${basedir}/target/docbook">
<include name="**/*.epub" />
</fileset>
</copy>
<move file="${basedir}/target/contents/reference/epub/index.epub"
tofile="${basedir}/target/contents/reference/epub/spring-boot-reference.epub" />
</postProcess>
</configuration>
</execution>
</executions>
</plugin>
<plugin> <plugin>
<groupId>org.apache.maven.plugins</groupId> <groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-antrun-plugin</artifactId> <artifactId>maven-antrun-plugin</artifactId>
@ -1421,6 +1346,7 @@
src="${project.build.directory}/${project.artifactId}-${revision}-javadoc.jar" src="${project.build.directory}/${project.artifactId}-${revision}-javadoc.jar"
prefix="api" /> prefix="api" />
<fileset dir="${project.build.directory}/contents" /> <fileset dir="${project.build.directory}/contents" />
<fileset dir="${project.build.directory}/generated-docs" />
</zip> </zip>
</target> </target>
</configuration> </configuration>

8
spring-boot-project/spring-boot-docs/src/main/asciidoc/documentation-overview.adoc
View File

@ -12,14 +12,8 @@ as a map for the rest of the document.
[[boot-documentation-about]] [[boot-documentation-about]]
== About the Documentation == About the Documentation
The Spring Boot reference guide is available as
* {spring-boot-docs}/html[HTML]
* {spring-boot-docs}/pdf/spring-boot-reference.pdf[PDF]
* {spring-boot-docs}/epub/spring-boot-reference.epub[EPUB]
The latest copy The latest copy
is available at {spring-boot-docs-current}. of the reference documentation is available at {spring-boot-docs-current}.
Copies of this document may be made for your own use and for distribution to others, Copies of this document may be made for your own use and for distribution to others,
provided that you do not charge any fee for such copies and further provided that each provided that you do not charge any fee for such copies and further provided that each

7
spring-boot-project/spring-boot-parent/pom.xml
View File

@ -294,7 +294,7 @@
<plugin> <plugin>
<groupId>org.asciidoctor</groupId> <groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId> <artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.5</version> <version>1.5.7.1</version>
</plugin> </plugin>
<plugin> <plugin>
<groupId>org.apache.maven.plugins</groupId> <groupId>org.apache.maven.plugins</groupId>
@ -313,6 +313,11 @@
<artifactId>maven-plugin-plugin</artifactId> <artifactId>maven-plugin-plugin</artifactId>
<version>3.5</version> <version>3.5</version>
</plugin> </plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-resources-plugin</artifactId>
<version>3.1.0</version>
</plugin>
<plugin> <plugin>
<groupId>org.apache.maven.plugins</groupId> <groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-site-plugin</artifactId> <artifactId>maven-site-plugin</artifactId>