SpringCloud/spring-cloud-build
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Started to publish the docs module as a jar

Browse Source 
without this change we copy paste all the scripts, resources etc. to every single project
with this change each project will have this project's resources unpacked in the local `target` directory. The docs generation already reference this changed location so no need to copy paste of any resources is required

fixes #60
This commit is contained in:
Marcin Grzejszczak
2017-08-31 13:48:43 +02:00
parent 0269b4a8b6
commit 4d0246d73e
3 changed files with 105 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
docs/pom.xml Normal file
View File

@@ -0,0 +1,27 @@
<?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 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<artifactId>spring-cloud-build-docs</artifactId>
<name>spring-cloud-build-docs</name>
<packaging>jar</packaging>
<description>Spring Cloud Build Docs</description>
<parent>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-build</artifactId>
<version>1.3.5.BUILD-SNAPSHOT</version>
</parent>
<build>
<resources>
<resource>
<directory>src/main</directory>
</resource>
</resources>
<plugins>
<plugin>
<artifactId>maven-deploy-plugin</artifactId>
<version>2.8.2</version>
</plugin>
</plugins>
</build>
</project>

41
docs/src/main/asciidoc/README.adoc
View File

@@ -41,3 +41,44 @@ $ mvn deploy -P central -DaltReleaseDeploymentRepository=sonatype-nexus-staging:
== Contributing
include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/contributing.adoc[]
== Reusing the documentation
Spring Cloud Build publishes its `spring-cloud-build-docs` module that contains
helpful scripts (e.g. README generation ruby script) and css, xslt and images
for the Spring Cloud documentation. If you want to follow the same convention
approach of generating documentation just add these plugins to your `docs` module
[source,xml]
----
<profiles>
<profile>
<id>docs</id>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId> <1>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId> <2>
</plugin>
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId> <3>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-antrun-plugin</artifactId> <4>
<inherited>false</inherited>
</plugin>
</plugins>
</build>
</profile>
</profiles>
----
<1> This plugin downloads and unpacks the resources of the `spring-cloud-build-docs` module
<2> This plugin is required to parse the Asciidoctor documentation
<3> This plugin converts the Asciidoctor documentation into single and multi page docs
<4> This plugin is required to copy resources into proper final destinations and to generate main README.adoc

46
pom.xml
View File

@@ -9,6 +9,7 @@
<name>Spring Cloud Parent</name>
<description>Spring Cloud parent pom, managing plugins and dependencies for Spring Cloud projects</description>
<modules>
<module>docs</module>
<module>spring-cloud-build-dependencies</module>
<module>spring-cloud-dependencies-parent</module>
<module>spring-cloud-build-tools</module>
@@ -631,6 +632,33 @@ limitations under the License.
<build>
<pluginManagement>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<version>3.0.0</version>
<executions>
<execution>
<id>unpack-docs</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-build-docs</artifactId>
<version>${spring-cloud-build.version}</version>
<classifier>sources</classifier>
<type>jar</type>
<overWrite>false</overWrite>
<outputDirectory>${project.build.directory}/build-docs</outputDirectory>
</artifactItem>
</artifactItems>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
@@ -694,10 +722,10 @@ limitations under the License.
<includes>${docs.main}.xml</includes>
<xincludeSupported>true</xincludeSupported>
<chunkedOutput>false</chunkedOutput>
<foCustomization>${basedir}/src/main/docbook/xsl/pdf.xsl</foCustomization>
<foCustomization>${project.build.directory}/build-docs/docbook/xsl/pdf.xsl</foCustomization>
<useExtensions>1</useExtensions>
<highlightSource>1</highlightSource>
<highlightXslthlConfig>${basedir}/src/main/docbook/xsl/xslthl-config.xml</highlightXslthlConfig>
<highlightXslthlConfig>${project.build.directory}/build-docs/docbook/xsl/xslthl-config.xml</highlightXslthlConfig>
</configuration>
<dependencies>
<dependency>
@@ -722,7 +750,7 @@ limitations under the License.
</goals>
<phase>prepare-package</phase>
<configuration>
<htmlCustomization>${basedir}/src/main/docbook/xsl/html-singlepage.xsl</htmlCustomization>
<htmlCustomization>${project.build.directory}/build-docs/docbook/xsl/html-singlepage.xsl</htmlCustomization>
<targetDirectory>${basedir}/target/docbook/htmlsingle</targetDirectory>
<postProcess>
<copy todir="${basedir}/target/contents/reference/htmlsingle">
@@ -731,7 +759,7 @@ limitations under the License.
</fileset>
</copy>
<copy todir="${basedir}/target/contents/reference/htmlsingle">
<fileset dir="${basedir}/src/main/docbook">
<fileset dir="${project.build.directory}/build-docs/docbook">
<include name="**/*.css" />
<include name="**/*.png" />
<include name="**/*.gif" />
@@ -748,7 +776,7 @@ limitations under the License.
</goals>
<phase>prepare-package</phase>
<configuration>
<htmlCustomization>${basedir}/src/main/docbook/xsl/html-multipage.xsl</htmlCustomization>
<htmlCustomization>${project.build.directory}/build-docs/docbook/xsl/html-multipage.xsl</htmlCustomization>
<targetDirectory>${basedir}/target/docbook/html</targetDirectory>
<!-- By default `-` prefix is added to files and gh-pages don't render these files -->
<chunkedFilenamePrefix>multi_</chunkedFilenamePrefix>
@@ -760,7 +788,7 @@ limitations under the License.
</fileset>
</copy>
<copy todir="${basedir}/target/contents/reference/html">
<fileset dir="${basedir}/src/main/docbook">
<fileset dir="${project.build.directory}/build-docs/docbook">
<include name="**/*.css" />
<include name="**/*.png" />
<include name="**/*.gif" />
@@ -824,7 +852,7 @@ limitations under the License.
<configuration>
<target>
<java classname="org.jruby.Main" failonerror="yes">
<arg value="${basedir}/src/main/ruby/generate_readme.sh"/>
<arg value="${project.build.directory}/build-docs/ruby/generate_readme.sh"/>
<arg value="-o"/>
<arg value="${main.basedir}/README.adoc"/>
</java>
@@ -840,10 +868,10 @@ limitations under the License.
<configuration>
<target>
<copy todir="${basedir}/target/generated-docs/css">
<fileset dir="${basedir}/src/main/docbook/css"/>
<fileset dir="${project.build.directory}/build-docs/docbook/css"/>
</copy>
<copy failonerror="false" todir="${basedir}/target/generated-docs/images">
<fileset dir="${basedir}/src/main/docbook/images"/>
<fileset dir="${project.build.directory}/build-docs/docbook/images"/>
</copy>
</target>
</configuration>