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)
## Enabling Maven Site generation
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 \ is configured to use your project's namespace.
4.0.0
org.opendaylight.PROJECT
deploy-site
1.0.0-SNAPSHOT
pom
latest
dav:https://nexus.opendaylight.org/content/sites/site/${project.groupId}/${stream}/
org.apache.maven.wagon
wagon-webdav-jackrabbit
2.9
org.apache.maven.plugins
maven-site-plugin
3.4
${project.build.directory}/staged-site
opendaylight-site
${nexus.site.url}
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.
## Fix Maven Site URLs
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).
${odl.site.url}/${project.groupId}/${stream}/${project.artifactId}/
opendaylight-site
${nexus.site.url}/${project.artifactId}/
**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.
## Customize project site
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