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

#1024 - Publish documentation using CI server.

Browse Source 
By letting the CI server assemble and publish documentation to docs.spring.io, we can ensure publicly posted docs are up-to-date.

Resolves #1037 by backporting to 0.25.x.
This commit is contained in:
Greg Turnquist
2019-07-17 14:35:16 -05:00
parent c64aaacd46
commit db1fa0acd5
3 changed files with 349 additions and 166 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
Jenkinsfile vendored
View File

@@ -102,6 +102,36 @@ pipeline {
}
}
}
stage('Release documentation') {
when {
anyOf {
branch '0.25.x'
branch 'release-0.x'
}
}
agent {
docker {
image 'springci/spring-hateoas-openjdk8-with-graphviz-and-jq:latest'
args '-v $HOME/.m2:/tmp/jenkins-home/.m2'
}
}
options { timeout(time: 20, unit: 'MINUTES') }
environment {
ARTIFACTORY = credentials('02bd1690-b54f-4c9f-819d-a77cb7a9822c')
}
steps {
script {
sh 'MAVEN_OPTS="-Duser.name=jenkins -Duser.home=/tmp/jenkins-home" ./mvnw -Pci,distribute ' +
'-Dartifactory.server=https://repo.spring.io ' +
"-Dartifactory.username=${ARTIFACTORY_USR} " +
"-Dartifactory.password=${ARTIFACTORY_PSW} " +
"-Dartifactory.distribution-repository=temp-private-local " +
'-Dmaven.test.skip=true deploy -B'
}
}
}
stage('Promote to Bintray') {
when {
branch 'release-0.x'

445
pom.xml
View File

@@ -1,5 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<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 https://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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>org.springframework.hateoas</groupId>
@@ -48,20 +49,20 @@
<name>Apache License, Version 2.0</name>
<url>https://www.apache.org/licenses/LICENSE-2.0</url>
<comments>
Copyright 2011 the original author or authors.
Copyright 2011-2019 the original author or authors.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied.
See the License for the specific language governing permissions and
limitations under the License.
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied.
See the License for the specific language governing permissions and
limitations under the License.
</comments>
</license>
</licenses>
@@ -199,29 +200,27 @@
<profile>
<!--
Profile to be activated when building the distribution atrifacts.
Generates reference documentation, aggregates JavaDoc etc.
Profile to be activated when building the docs artifacts.
-->
<id>distribute</id>
<properties>
<shared.resources>${project.build.directory}/shared-resources</shared.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.main.skip>true</maven.main.skip>
<maven.test.skip>true</maven.test.skip>
<maven.kotlin.skip>true</maven.kotlin.skip>
<maven.install.skip>true</maven.install.skip>
<maven.deploy.skip>true</maven.deploy.skip>
<skipTests>true</skipTests>
<project.root>${basedir}</project.root>
<docs.resources.version>0.1.0.RELEASE</docs.resources.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.data.build</groupId>
<artifactId>spring-data-build-resources</artifactId>
<version>1.9.13.RELEASE</version>
<scope>provided</scope>
<type>zip</type>
</dependency>
<dependency>
<groupId>io.spring.docresources</groupId>
<artifactId>spring-doc-resources</artifactId>
@@ -229,6 +228,13 @@
<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>
<type>zip</type>
<optional>true</optional>
</dependency>
</dependencies>
<build>
@@ -243,13 +249,6 @@
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<executions>
<execution>
<id>unpack-shared-resources</id>
<goals>
<goal>unpack-dependencies</goal>
</goals>
<phase>generate-resources</phase>
</execution>
<execution>
<id>unpack-doc-resources</id>
<goals>
@@ -261,23 +260,49 @@
<includeArtifactIds>spring-doc-resources</includeArtifactIds>
<includeTypes>zip</includeTypes>
<excludeTransitive>true</excludeTransitive>
<outputDirectory>${project.build.directory}/refdocs/</outputDirectory>
<outputDirectory>${generated-asciidoc-sources.directory}</outputDirectory>
</configuration>
</execution>
<execution>
<id>unpack-shared-resources</id>
<goals>
<goal>unpack-dependencies</goal>
</goals>
<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>org.springframework.data</includeGroupIds>
<includeArtifactIds>spring-data-build-resources</includeArtifactIds>
<includeTypes>zip</includeTypes>
<excludeTransitive>true</excludeTransitive>
<outputDirectory>${shared.resources}</outputDirectory>
</configuration>
</plugin>
<!--
Configures JavaDoc generation.
-->
<!-- Delombok sources so that generated code shows up in JavaDoc -->
<plugin>
<groupId>org.projectlombok</groupId>
<artifactId>lombok-maven-plugin</artifactId>
<version>1.18.4.0</version>
<executions>
<execution>
<phase>generate-sources</phase>
<goals>
<goal>delombok</goal>
</goals>
<configuration>
<outputDirectory>${project.root}/target/generated-sources/delombok</outputDirectory>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
@@ -285,104 +310,18 @@
<execution>
<id>aggregate-javadoc</id>
<goals>
<goal>javadoc</goal>
<goal>aggregate</goal>
</goals>
<phase>package</phase>
<configuration>
<outputDirectory>${project.root}/target/site/apidocs</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>${project.build.directory}/refdocs/</outputDirectory>
<resources>
<resource>
<directory>src/main/asciidoc</directory>
<filtering>false</filtering>
</resource>
</resources>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.7.1</version>
<dependencies>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-pdf</artifactId>
<version>1.5.0-alpha.16</version>
</dependency>
</dependencies>
<executions>
<execution>
<id>html</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>html5</backend>
<sourceHighlighter>highlight.js</sourceHighlighter>
<outputDirectory>${project.build.directory}/site/reference/html</outputDirectory>
<sectids>false</sectids>
<attributes>
<docinfo>shared</docinfo>
<linkcss>true</linkcss>
<icons>font</icons>
<sectanchors>true</sectanchors>
<stylesdir>css/</stylesdir>
<stylesheet>spring.css</stylesheet>
<highlightjsdir>js/highlight</highlightjsdir>
<highlightjs-theme>atom-one-dark-reasonable</highlightjs-theme>
</attributes>
</configuration>
</execution>
<execution>
<id>pdf</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>pdf</backend>
<sourceHighlighter>coderay</sourceHighlighter>
</configuration>
</execution>
</executions>
<configuration>
<sourceDirectory>${project.build.directory}/refdocs/</sourceDirectory>
<doctype>book</doctype>
<attributes>
<version>${project.version}</version>
<projectName>${project.name}</projectName>
<projectVersion>${project.version}</projectVersion>
<allow-uri-read>true</allow-uri-read>
<toclevels>4</toclevels>
<numbered>true</numbered>
<baseDir>${project.basedir}</baseDir>
</attributes>
</configuration>
</plugin>
<plugin>
<artifactId>maven-antrun-plugin</artifactId>
<version>1.8</version>
<executions>
@@ -392,13 +331,39 @@
<phase>generate-resources</phase>
<configuration>
<target>
<copy todir="${project.root}/target/site/reference/html/images">
<copy todir="target/site/reference/html/images">
<fileset dir="${basedir}/src/main/asciidoc" erroronmissingdir="false">
<include name="**/*.png" />
<include name="**/*.gif" />
<include name="**/*.jpg" />
<include name="**/*.png"/>
<include name="**/*.gif"/>
<include name="**/*.jpg"/>
</fileset>
<flattenmapper/>
</copy>
</target>
</configuration>
<goals>
<goal>run</goal>
</goals>
</execution>
<execution>
<id>create-generated-docs-resources</id>
<phase>process-resources</phase>
<configuration>
<target>
<copy failonerror="false" todir="${generated-asciidoc-sources.directory}/">
<fileset dir="src/main/asciidoc" includes="**/*.adoc"/>
</copy>
<copy failonerror="false"
todir="${generated-asciidoc-sources.directory}/images/">
<fileset dir="src/main/asciidoc/images"/>
</copy>
<copy todir="${generated-docs.directory}">
<fileset dir="${generated-asciidoc-sources.directory}">
<include name="css/**"/>
<include name="js/**"/>
</fileset>
<flattenmapper />
</copy>
</target>
</configuration>
@@ -409,10 +374,43 @@
<execution>
<id>rename-reference-docs</id>
<phase>process-resources</phase>
<phase>prepare-package</phase>
<configuration>
<target>
<copy file="${project.build.directory}/generated-docs/index.pdf" tofile="${project.root}/target/site/reference/pdf/${project.artifactId}-reference.pdf" failonerror="false" />
<!-- Copy files for the single-file HTML version -->
<copy failonerror="false"
todir="target/site/reference/html/images">
<fileset dir="${generated-docs.directory}/images"/>
</copy>
<!-- Copy shared resources. Spring Data ones first to override the ones shared -->
<copy failonerror="false" todir="target/site/reference/html/">
<fileset dir="${shared.resources}">
<include name="css/**"/>
<include name="js/**"/>
</fileset>
</copy>
<copy failonerror="false" todir="target/site/reference/html/">
<fileset dir="${generated-asciidoc-sources.directory}">
<include name="css/**"/>
<include name="js/**"/>
</fileset>
</copy>
<copy failonerror="false" todir="target/site/reference/html/">
<fileset dir="${generated-docs.directory}" includes="*.html"/>
</copy>
<!-- Copy and rename the Epub file -->
<copy failonerror="false" file="${generated-docs.directory}/index.pdf"
tofile="target/site/reference/pdf/spring-hateoas-reference.pdf"/>
<!-- Copy and rename the PDF file -->
<copy failonerror="false" file="${generated-docs.directory}/index.epub"
tofile="target/site/reference/epub/spring-hateoas-reference.epub"/>
</target>
</configuration>
<goals>
@@ -420,69 +418,184 @@
</goals>
</execution>
<execution>
<id>package-and-attach-docs-zip</id>
<phase>package</phase>
<goals>
<goal>run</goal>
</goals>
<configuration>
<tasks>
<zip destfile="${project.build.directory}/${project.artifactId}-${project.version}.zip">
<fileset dir="${project.build.directory}/site" />
</zip>
</tasks>
</configuration>
</execution>
</executions>
</plugin>
<!--
Asciidoctor
-->
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>build-helper-maven-plugin</artifactId>
<version>1.10</version>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>2.0.0-RC.1</version>
<dependencies>
<dependency>
<groupId>org.jruby</groupId>
<artifactId>jruby</artifactId>
<version>9.2.6.0</version>
</dependency>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj</artifactId>
<version>2.0.0-RC.1</version>
</dependency>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-pdf</artifactId>
<version>1.5.0-alpha.16</version>
</dependency>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-epub3</artifactId>
<version>1.5.0-alpha.8.1</version>
</dependency>
</dependencies>
<executions>
<execution>
<id>attach-zip</id>
<id>html</id>
<phase>compile</phase>
<goals>
<goal>attach-artifact</goal>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<artifacts>
<artifact>
<file>${project.build.directory}/${project.artifactId}-${project.version}.zip</file>
<type>zip</type>
</artifact>
</artifacts>
<sourceDirectory>${generated-asciidoc-sources.directory}</sourceDirectory>
<sourceDocumentName>index.adoc</sourceDocumentName>
<backend>html5</backend>
<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>
<sectanchors>true</sectanchors>
<stylesdir>./css</stylesdir>
<stylesheet>spring.css</stylesheet>
<toc>left</toc>
</attributes>
</configuration>
</execution>
<!-- Requires a fix to Lombok/Javadoc generation first otherwise build duration explodes
<execution>
<id>epub</id>
<phase>compile</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<sourceDirectory>${generated-asciidoc-sources.directory}</sourceDirectory>
<sourceDocumentName>index.adoc</sourceDocumentName>
<backend>epub3</backend>
<outputDirectory>${generated-docs.directory}</outputDirectory>
<sourceHighlighter>coderay</sourceHighlighter>
</configuration>
</execution>
<execution>
<id>pdf</id>
<phase>compile</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<sourceDirectory>${generated-asciidoc-sources.directory}</sourceDirectory>
<sourceDocumentName>index.adoc</sourceDocumentName>
<backend>pdf</backend>
<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>
<springVersion>${spring.version}</springVersion>
<allow-uri-read>true</allow-uri-read>
<toclevels>4</toclevels>
<numbered>true</numbered>
</attributes>
</configuration>
</plugin>
<!--
Creates two zip files for download as well as API and reference documentation distribution.
-->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-assembly-plugin</artifactId>
<version>3.1.0</version>
<executions>
<execution>
<id>static</id>
<id>docs</id>
<goals>
<goal>single</goal>
</goals>
<phase>package</phase>
<configuration>
<descriptors>
<descriptor>${shared.resources}/assemblies/static-resources.xml</descriptor>
<descriptor>src/docs/resources/assemblies/docs.xml</descriptor>
</descriptors>
<finalName>static-resources</finalName>
<appendAssemblyId>false</appendAssemblyId>
<finalName>spring-hateoas-${project.version}</finalName>
<appendAssemblyId>true</appendAssemblyId>
</configuration>
</execution>
</executions>
</plugin>
<!-- Deploy to Artifactory -->
<plugin>
<groupId>org.jfrog.buildinfo</groupId>
<artifactId>artifactory-maven-plugin</artifactId>
<version>2.6.1</version>
<executions>
<execution>
<id>deploy-docs</id>
<goals>
<goal>publish</goal>
</goals>
<phase>deploy</phase>
<configuration>
<artifactory>
<includeEnvVars>false</includeEnvVars>
</artifactory>
<deployProperties>
<zip.name>spring-hateoas-docs</zip.name>
<zip.displayname>spring-hateoas-docs</zip.displayname>
<zip.deployed>false</zip.deployed>
<zip.type>docs</zip.type>
</deployProperties>
<buildInfo>
<!-- Retain only a single build -->
<buildName>Spring Data Docs spring-hateoas ${project.version}</buildName>
<buildRetentionCount>1</buildRetentionCount>
</buildInfo>
<publisher>
<contextUrl>{{artifactory.server}}</contextUrl>
<username>{{artifactory.username}}</username>
<password>{{artifactory.password}}</password>
<repoKey>{{artifactory.distribution-repository}}</repoKey>
<snapshotRepoKey>{{artifactory.distribution-repository}}</snapshotRepoKey>
<includePatterns>*-docs.zip</includePatterns>
</publisher>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>

40
src/main/resources/assemblies/docs.xml Normal file
View File

@@ -0,0 +1,40 @@
<?xml version="1.0" encoding="UTF-8"?>
<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2 https://maven.apache.org/xsd/assembly-1.1.2.xsd">
<id>docs</id>
<formats>
<format>dir</format>
<format>zip</format>
</formats>
<includeBaseDirectory>false</includeBaseDirectory>
<fileSets>
<fileSet>
<!--
Adds readme and other textfiles to the root of the distribution archive.
-->
<directory>src/main/resources</directory>
<includes>
<include>changelog.txt</include>
<include>license.txt</include>
<include>notice.txt</include>
</includes>
<outputDirectory />
<lineEnding>dos</lineEnding>
</fileSet>
<fileSet>
<!--
Adds reference manual (html and pdf) to the distribution archive
under the 'docs/reference' directory see pom.xml 'maven-javadoc-plugin' declaration.
-->
<directory>target/site/reference</directory>
<outputDirectory>reference</outputDirectory>
</fileSet>
<fileSet>
<!--
Adds javadoc html to the distribution archive under the 'docs/javadoc'
directory see pom.xml 'maven-javadoc-plugin' declaration.
-->
<directory>target/site/apidocs</directory>
<outputDirectory>api</outputDirectory>
</fileSet>
</fileSets>
</assembly>