From 363c81710861e15bc8ab010e290d10a9f4cedfa5 Mon Sep 17 00:00:00 2001
From: Mark Paluch <mpaluch@pivotal.io>
Date: Mon, 10 Dec 2018 09:56:10 +0100
Subject: [PATCH] #566 - Polishing.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

We now use spring-doc-resources that contains CSS and JavaScript for our reference documentation. External doc resources requires an intermediate asciidoc sources directory to include docinfo files. Documentation generation hence now unpacks Spring Data Build resources and Spring Doc resources, generates an intermediate sources directory and compiles documentation from there.

Multi-module projects require a slight adjustment of their external (e.g. Spring Data Commons) imports as doc generation happens typically within the context of a …-distribute module.

Original pull request: #545.
---
 parent/pom.xml | 159 ++++++++++++++++++++++++++-----------------------
 1 file changed, 83 insertions(+), 76 deletions(-)

diff --git a/parent/pom.xml b/parent/pom.xml
index 523090ee..0857df8e 100644
--- a/parent/pom.xml
+++ b/parent/pom.xml
@@ -1,5 +1,6 @@
 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+		 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
 
 	<!--
 
@@ -244,25 +245,27 @@
 
 			<properties>
 				<shared.resources>${project.build.directory}/shared-resources</shared.resources>
-				<doc.resources>${project.build.directory}/doc-resources</doc.resources>
+				<generated-asciidoc-sources.directory>${project.build.directory}/generated-asciidoc-sources/source/
+				</generated-asciidoc-sources.directory>
+				<generated-docs.directory>${project.build.directory}/generated-docs</generated-docs.directory>
 				<maven.install.skip>true</maven.install.skip>
 				<skipTests>true</skipTests>
 			</properties>
 
 			<dependencies>
 				<dependency>
-					<groupId>org.springframework.doc-resources</groupId>
+					<groupId>io.spring.docresources</groupId>
 					<artifactId>spring-doc-resources</artifactId>
-					<version>0.1.1-SNAPSHOT</version>
-					<scope>provided</scope>
+					<version>0.1.0-BUILD-SNAPSHOT</version>
 					<type>zip</type>
+					<optional>true</optional>
 				</dependency>
 				<dependency>
 					<groupId>org.springframework.data.build</groupId>
 					<artifactId>spring-data-build-resources</artifactId>
 					<version>2.2.0.BUILD-SNAPSHOT</version>
-					<scope>provided</scope>
 					<type>zip</type>
+					<optional>true</optional>
 				</dependency>
 			</dependencies>
 
@@ -283,40 +286,38 @@
 								<goals>
 									<goal>unpack-dependencies</goal>
 								</goals>
-								<phase>prepare-package</phase>
+								<phase>generate-resources</phase>
+								<configuration>
+									<includeGroupIds>${project.groupId}</includeGroupIds>
+									<includeArtifactIds>spring-data-build-resources</includeArtifactIds>
+									<includeTypes>zip</includeTypes>
+									<excludeTransitive>true</excludeTransitive>
+									<outputDirectory>${shared.resources}</outputDirectory>
+								</configuration>
 							</execution>
-						</executions>
-						<configuration>
-							<includeGroupIds>${project.groupId}</includeGroupIds>
-							<includeArtifacIds>spring-data-build-resources</includeArtifacIds>
-							<includeTypes>zip</includeTypes>
-							<excludeTransitive>true</excludeTransitive>
-							<outputDirectory>${shared.resources}</outputDirectory>
-						</configuration>
-					</plugin>
 
-					<!--
-						Unpacks the content of spring-doc-resources into the doc resources folder.
-					-->
-
-					<plugin>
-						<groupId>org.apache.maven.plugins</groupId>
-						<artifactId>maven-dependency-plugin</artifactId>
-						<executions>
 							<execution>
-								<id>unpack-shared-resources</id>
+								<id>unpack-doc-resources</id>
 								<goals>
 									<goal>unpack-dependencies</goal>
 								</goals>
-								<phase>initialize</phase>
+								<phase>generate-resources</phase>
+								<configuration>
+									<includeGroupIds>io.spring.docresources</includeGroupIds>
+									<includeArtifactIds>spring-doc-resources</includeArtifactIds>
+									<includeTypes>zip</includeTypes>
+									<excludeTransitive>true</excludeTransitive>
+									<outputDirectory>${generated-asciidoc-sources.directory}</outputDirectory>
+								</configuration>
 							</execution>
 						</executions>
+					</plugin>
+
+					<plugin>
+						<groupId>org.apache.maven.plugins</groupId>
+						<artifactId>maven-compiler-plugin</artifactId>
 						<configuration>
-							<includeGroupIds>org.springframework.doc-resources</includeGroupIds>
-							<includeArtifactIds>spring-doc-resources</includeArtifactIds>
-							<includeTypes>zip</includeTypes>
-							<excludeTransitive>true</excludeTransitive>
-							<outputDirectory>${doc.resources}</outputDirectory>
+							<skip>true</skip>
 						</configuration>
 					</plugin>
 
@@ -408,26 +409,22 @@
 							</execution>
 
 							<execution>
-								<id>create-docs-working-directory</id>
-								<phase>initialize</phase>
+								<id>create-generated-docs-resources</id>
+								<phase>process-resources</phase>
 								<configuration>
 									<target>
-										<copy failonerror="false" file="${project.build.directory}/doc-resources/stylesheets/spring.css" tofile="${project.build.directory}/working/stylesheets/spring.css"/>
-										<copy failonerror="false" file="${project.build.directory}/doc-resources/html/docinfo.html" tofile="${project.build.directory}/working/docinfo.html"/>
-										<copy failonerror="false" file="${project.build.directory}/doc-resources/html/docinfo-footer.html" tofile="${project.build.directory}/working/docinfo-footer.html"/>
-										<copy failonerror="false" todir="${project.build.directory}/working/tocbot-3.0.2">
-											<fileset dir="${project.build.directory}/doc-resources/javascript/tocbot-3.0.2">
-												<include name="*.*"/>
-											</fileset>
+										<copy failonerror="false" todir="${generated-asciidoc-sources.directory}/">
+											<fileset dir="${project.root}/src/main/asciidoc" includes="**/*.adoc"/>
 										</copy>
-										<copy failonerror="false" todir="${project.build.directory}/working">
-											<fileset dir="${project.root}/src/main/asciidoc">
-												<include name="**/*.adoc"/>
-											</fileset>
+										<copy failonerror="false"
+											  todir="${generated-asciidoc-sources.directory}/images/">
+											<fileset dir="${project.root}/src/main/asciidoc/images"/>
 										</copy>
-										<copy failonerror="false" todir="${project.build.directory}/working/images">
-											<fileset dir="${project.root}/src/main/asciidoc/images">
-												<include name="*.*"/>
+
+										<copy todir="${generated-docs.directory}">
+											<fileset dir="${generated-asciidoc-sources.directory}">
+												<include name="css/**"/>
+												<include name="js/**"/>
 											</fileset>
 										</copy>
 									</target>
@@ -439,29 +436,34 @@
 
 							<execution>
 								<id>rename-reference-docs</id>
-								<phase>package</phase>
+								<phase>prepare-package</phase>
 								<configuration>
 									<target>
 
 										<!-- Copy files for the single-file HTML version -->
-										<copy failonerror="false" file="${project.build.directory}/generated-docs/index.html" tofile="${project.root}/target/site/reference/html/${dist.id}-reference.html"/>
-										<copy failonerror="false" todir="${project.root}/target/site/reference/html/images">
-											<fileset dir="${project.build.directory}/generated-docs/images">
-												<include name="*.*"/>
+										<copy failonerror="false"
+											  todir="${project.root}/target/site/reference/html/images">
+											<fileset dir="${generated-docs.directory}/images"/>
+										</copy>
+
+										<copy failonerror="false" todir="${project.root}/target/site/reference/html/">
+											<fileset dir="${generated-asciidoc-sources.directory}">
+												<include name="css/**"/>
+												<include name="js/**"/>
 											</fileset>
 										</copy>
-										<copy failonerror="false" todir="${project.root}/target/site/reference/html/tocbot-3.0.2">
-											<fileset dir="${project.build.directory}/generated-docs/tocbot-3.0.2">
-												<include name="*.*"/>
-											</fileset>
+
+										<copy failonerror="false" todir="${project.root}/target/site/reference/html/">
+											<fileset dir="${generated-docs.directory}" includes="*.html" />
 										</copy>
-										<copy failonerror="false" file="${project.build.directory}/generated-docs/stylesheets/spring.css" tofile="${project.root}/target/site/reference/html/stylesheets/spring.css"/>
 
 										<!-- Copy and rename the Epub file -->
-										<copy failonerror="false" file="${project.build.directory}/generated-docs/index.pdf" tofile="${project.root}/target/site/reference/pdf/${dist.id}-reference.pdf"/>
+										<copy failonerror="false" file="${generated-docs.directory}/index.pdf"
+											  tofile="${project.root}/target/site/reference/pdf/${dist.id}-reference.pdf"/>
 
 										<!-- Copy and rename the PDF file -->
-										<copy failonerror="false" file="${project.build.directory}/generated-docs/index.epub" tofile="${project.root}/target/site/reference/epub/${dist.id}-reference.epub"/>
+										<copy failonerror="false" file="${generated-docs.directory}/index.epub"
+											  tofile="${project.root}/target/site/reference/epub/${dist.id}-reference.epub"/>
 
 									</target>
 								</configuration>
@@ -502,66 +504,71 @@
 
 								<execution>
 									<id>html</id>
-									<phase>prepare-package</phase>
+									<phase>compile</phase>
 									<goals>
 										<goal>process-asciidoc</goal>
 									</goals>
 									<configuration>
-										<sourceDirectory>${project.build.directory}/working</sourceDirectory>
+										<sourceDirectory>${generated-asciidoc-sources.directory}</sourceDirectory>
+										<sourceDocumentName>index.adoc</sourceDocumentName>
 										<backend>html5</backend>
-										<outputDirectory>${project.build.directory}/generated-docs</outputDirectory>
-										<sectids>false</sectids>
-										<sourceHighlighter>prettify</sourceHighlighter>
+										<outputDirectory>${generated-docs.directory}</outputDirectory>
+										<sourceHighlighter>highlight.js</sourceHighlighter>
 										<attributes>
+											<highlightjsdir>js/highlight</highlightjsdir>
+											<highlightjs-theme>atom-one-dark-reasonable</highlightjs-theme>
 											<linkcss>true</linkcss>
-											<icons>font</icons>
 											<sectanchors>true</sectanchors>
-											<stylesdir>./stylesheets</stylesdir>
+											<stylesdir>./css</stylesdir>
 											<stylesheet>spring.css</stylesheet>
-											<docinfo>shared</docinfo>
 											<toc>left</toc>
 										</attributes>
 									</configuration>
 								</execution>
 
-
+								<!-- Requires a fix to Lombok/Javadoc generation first otherwise build duration explodes
 								<execution>
 									<id>epub</id>
-									<phase>prepare-package</phase>
+									<phase>compile</phase>
 									<goals>
 										<goal>process-asciidoc</goal>
 									</goals>
 									<configuration>
-										<sourceDirectory>${project.build.directory}/working</sourceDirectory>
+										<sourceDirectory>${generated-asciidoc-sources.directory}</sourceDirectory>
 										<sourceDocumentName>index.adoc</sourceDocumentName>
 										<backend>epub3</backend>
-										<outputDirectory>${project.build.directory}/generated-docs</outputDirectory>
-										<sectids>false</sectids>
+										<outputDirectory>${generated-docs.directory}</outputDirectory>
 										<sourceHighlighter>coderay</sourceHighlighter>
 									</configuration>
 								</execution>
 
 								<execution>
 									<id>pdf</id>
-									<phase>prepare-package</phase>
+									<phase>compile</phase>
 									<goals>
 										<goal>process-asciidoc</goal>
 									</goals>
 									<configuration>
-										<sourceDirectory>${project.build.directory}/working</sourceDirectory>
+										<sourceDirectory>${generated-asciidoc-sources.directory}</sourceDirectory>
 										<sourceDocumentName>index.adoc</sourceDocumentName>
 										<backend>pdf</backend>
-										<outputDirectory>${project.build.directory}/generated-docs</outputDirectory>
-										<sectids>false</sectids>
+										<outputDirectory>${generated-docs.directory}</outputDirectory>
 										<sourceHighlighter>coderay</sourceHighlighter>
 									</configuration>
 								</execution>
 
+								 -->
+
 							</executions>
 
 							<configuration>
 								<doctype>book</doctype>
 								<attributes>
+									<doctype>book</doctype>
+									<docinfo>shared</docinfo>
+									<icons>font</icons>
+									<sectids>false</sectids>
+									<imagesdir>images</imagesdir>
 									<version>${project.version}</version>
 									<projectName>${project.name}</projectName>
 									<projectVersion>${project.version}</projectVersion>