maven:
maven-name: '{mvn33}'
root-pom: 'POM'
- goals: 'MAVEN_GOALS -Dmerge'
+ goals: 'MAVEN_GOALS -Dmerge -Dstream={stream}'
maven-opts: 'MAVEN_OPTS'
settings: '{JENKINS_SETTINGS}'
global-settings: '{odl-global-settings}'
+ post-step-run-condition: UNSTABLE
+
+ postbuilders:
+ - conditional-step:
+ condition-kind: file-exists
+ condition-filename: deploy-site.xml
+ condition-basedir: workspace
+
+ # The strategy here is intentional to run Maven site:deploy twice
+ # once using regular pom.xml to produce a staged-site which is
+ # then used by deploy-site.xml to push to Nexus. This is a
+ # workaround to Maven Site's default linking code which creates
+ # incorrect URLs for sites due to auto-detection assuming your
+ # project is configured in a certain way which ODL is not.
+ steps:
+ - maven-target:
+ maven-version: '{mvn33}'
+ pom: pom.xml
+ goals: 'site:deploy -Dstream={stream}'
+ java-opts:
+ - '-Xmx2g'
+ settings: '{JENKINS_SETTINGS}'
+ global-settings: '{odl-global-settings}'
+ - maven-target:
+ maven-version: '{mvn33}'
+ pom: deploy-site.xml
+ goals: 'site:deploy -Dstream={stream}'
+ java-opts:
+ - '-Xmx2g'
+ settings: '{JENKINS_SETTINGS}'
+ global-settings: '{odl-global-settings}'
reporters:
- findbugs
--- /dev/null
+Maven Site is a handy tool for auto-generating a website containing site
+details for your project based on information scanned from project pom files.
+It can also be used to auto-generate coverage reports and Javadoc pages. This
+page will describe how to generate a Maven site for your ODL project.
+
+* [Enable Maven Site generation](#enable_site)
+* [Fix site urls](#fix_site_urls)
+* [Customize project site](#customize_site)
+
+## <a name="enable_site">Enabling Maven Site generation</a>
+
+The odlparent project provides most of the necessary configuration already to
+generate a Maven site for all ODL projects but the site generation is disabled
+by default. In order to enable site generation you will need to create a file
+called "deploy-site.xml" in the root of your project repo. This file's
+existance will cause the Maven build as well as ODL Jenkins system to start
+generating and deploying the site to Nexus.
+
+Below is an example configuration you can copy to create the deploy-site.xml
+this file is not too complicated and the only thing you need to change is to
+ensure that the \<groupId\> is configured to use your project's namespace.
+
+ <?xml version="1.0" encoding="UTF-8"?>
+ <!-- vi: set et smarttab sw=2 tabstop=2: -->
+ <!--
+ Copyright (c) 2015 The Linux Foundation and others. All rights reserved.
+
+ This program and the accompanying materials are made available under the
+ terms of the Eclipse Public License v1.0 which accompanies this distribution,
+ and is available at http://www.eclipse.org/legal/epl-v10.html
+ -->
+ <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>
+
+ <groupId>org.opendaylight.PROJECT</groupId>
+ <artifactId>deploy-site</artifactId>
+ <version>1.0.0-SNAPSHOT</version>
+ <packaging>pom</packaging>
+
+ <properties>
+ <stream>latest</stream>
+ <nexus.site.url>dav:https://nexus.opendaylight.org/content/sites/site/${project.groupId}/${stream}/</nexus.site.url>
+ </properties>
+
+ <build>
+ <extensions>
+ <extension>
+ <groupId>org.apache.maven.wagon</groupId>
+ <artifactId>wagon-webdav-jackrabbit</artifactId>
+ <version>2.9</version>
+ </extension>
+ </extensions>
+
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-site-plugin</artifactId>
+ <version>3.4</version>
+ <configuration>
+ <inputDirectory>${project.build.directory}/staged-site</inputDirectory>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+
+ <distributionManagement>
+ <site>
+ <id>opendaylight-site</id>
+ <url>${nexus.site.url}</url>
+ </site>
+ </distributionManagement>
+ </project>
+
+Note that the above file is a dummy file who's only purpose is to push a
+staged-site to Nexus as well as being the trigger for odlparent to activate
+site generation for your project.
+
+## <a name="fix_site_urls">Fix Maven Site URLs</a>
+
+The maven-site-plugin assumes projects are configured in a certain Maven way
+which unfortunately ODL is not configured as such. This causes the site plugin
+to generate invalid URLs to all project modules. The workaround for this is to
+pass both a url and a distribution.site.url for every single module in your
+Maven project. The following template should be placed into all modules in an
+ODL project with the exception of the root pom (this will be explained below the
+example).
+
+ <!--
+ Maven Site Configuration
+
+ The following configuration is necessary for maven-site-plugin to
+ correctly identify the correct deployment path for OpenDaylight Maven
+ sites.
+ -->
+ <url>${odl.site.url}/${project.groupId}/${stream}/${project.artifactId}/</url>
+
+ <distributionManagement>
+ <site>
+ <id>opendaylight-site</id>
+ <url>${nexus.site.url}/${project.artifactId}/</url>
+ </site>
+ </distributionManagement>
+
+**Note:** For the project root pom.xml remove the final path
+"${project.artifactId}" from both URLs. This is so that the root project
+can represent the root index page for your project when the Maven Site is
+deployed.
+
+## <a name="customize_site">Customize project site</a>
+
+In the root pom of your project you can create customized site including
+creating your own project Documentation via markdown (or other formats)
+using the maven-site-plugin. Please refer to Maven Site documentation for
+how to customize your site.
+
+The general documentation can be found here
+https://maven.apache.org/plugins/maven-site-plugin/
+
+The following pages are particularly useful regarding creating your site
+content:
+
+ * https://maven.apache.org/plugins/maven-site-plugin/examples/creating-content.html
+ * https://maven.apache.org/plugins/maven-site-plugin/examples/sitedescriptor.html
Code Review / releng / builder.git / commitdiff