src/site/markdown/maven-site.md

   1 Maven Site is a handy tool for auto-generating a website containing site
   2 details for your project based on information scanned from project pom files.
   3 It can also be used to auto-generate coverage reports and Javadoc pages. This
   4 page will describe how to generate a Maven site for your ODL project.
   5
   6 * [Enable Maven Site generation](#enable_site)
   7 * [Fix site urls](#fix_site_urls)
   8 * [Customize project site](#customize_site)
   9
  10 ## <a name="enable_site">Enabling Maven Site generation</a>
  11
  12 The odlparent project provides most of the necessary configuration already to
  13 generate a Maven site for all ODL projects but the site generation is disabled
  14 by default. In order to enable site generation you will need to create a file
  15 called "deploy-site.xml" in the root of your project repo. This file's
  16 existance will cause the Maven build as well as ODL Jenkins system to start
  17 generating and deploying the site to Nexus.
  18
  19 Below is an example configuration you can copy to create the deploy-site.xml
  20 this file is not too complicated and the only thing you need to change is to
  21 ensure that the \<groupId\> is configured to use your project's namespace.
  22
  23     <?xml version="1.0" encoding="UTF-8"?>
  24     <!-- vi: set et smarttab sw=2 tabstop=2: -->
  25     <!--
  26         Copyright (c) 2015 The Linux Foundation and others.  All rights reserved.
  27
  28         This program and the accompanying materials are made available under the
  29         terms of the Eclipse Public License v1.0 which accompanies this distribution,
  30         and is available at http://www.eclipse.org/legal/epl-v10.html
  31     -->
  32     <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">
  33       <modelVersion>4.0.0</modelVersion>
  34
  35       <groupId>org.opendaylight.PROJECT</groupId>
  36       <artifactId>deploy-site</artifactId>
  37       <version>1.0.0-SNAPSHOT</version>
  38       <packaging>pom</packaging>
  39
  40       <properties>
  41         <stream>latest</stream>
  42         <nexus.site.url>dav:https://nexus.opendaylight.org/content/sites/site/${project.groupId}/${stream}/</nexus.site.url>
  43       </properties>
  44
  45       <build>
  46         <extensions>
  47           <extension>
  48             <groupId>org.apache.maven.wagon</groupId>
  49              <artifactId>wagon-webdav-jackrabbit</artifactId>
  50              <version>2.9</version>
  51           </extension>
  52         </extensions>
  53
  54         <plugins>
  55           <plugin>
  56             <groupId>org.apache.maven.plugins</groupId>
  57             <artifactId>maven-site-plugin</artifactId>
  58             <version>3.4</version>
  59             <configuration>
  60               <inputDirectory>${project.build.directory}/staged-site</inputDirectory>
  61             </configuration>
  62           </plugin>
  63         </plugins>
  64       </build>
  65
  66       <distributionManagement>
  67         <site>
  68           <id>opendaylight-site</id>
  69           <url>${nexus.site.url}</url>
  70         </site>
  71       </distributionManagement>
  72     </project>
  73
  74 Note that the above file is a dummy file who's only purpose is to push a
  75 staged-site to Nexus as well as being the trigger for odlparent to activate
  76 site generation for your project.
  77
  78 ## <a name="fix_site_urls">Fix Maven Site URLs</a>
  79
  80 The maven-site-plugin assumes projects are configured in a certain Maven way
  81 which unfortunately ODL is not configured as such. This causes the site plugin
  82 to generate invalid URLs to all project modules. The workaround for this is to
  83 pass both a url and a distribution.site.url for every single module in your
  84 Maven project. The following template should be placed into all modules in an
  85 ODL project with the exception of the root pom (this will be explained below the
  86 example).
  87
  88     <!--
  89         Maven Site Configuration
  90
  91         The following configuration is necessary for maven-site-plugin to
  92         correctly identify the correct deployment path for OpenDaylight Maven
  93         sites.
  94     -->
  95     <url>${odl.site.url}/${project.groupId}/${stream}/${project.artifactId}/</url>
  96
  97     <distributionManagement>
  98       <site>
  99         <id>opendaylight-site</id>
 100         <url>${nexus.site.url}/${project.artifactId}/</url>
 101       </site>
 102     </distributionManagement>
 103
 104 **Note:** For the project root pom.xml remove the final path
 105 "${project.artifactId}" from both URLs. This is so that the root project
 106 can represent the root index page for your project when the Maven Site is
 107 deployed.
 108
 109 ## <a name="customize_site">Customize project site</a>
 110
 111 In the root pom of your project you can create customized site including
 112 creating your own project Documentation via markdown (or other formats)
 113 using the maven-site-plugin. Please refer to Maven Site documentation for
 114 how to customize your site.
 115
 116 The general documentation can be found here
 117 https://maven.apache.org/plugins/maven-site-plugin/
 118
 119 The following pages are particularly useful regarding creating your site
 120 content:
 121
 122   * https://maven.apache.org/plugins/maven-site-plugin/examples/creating-content.html
 123   * https://maven.apache.org/plugins/maven-site-plugin/examples/sitedescriptor.html
 124
 125 ## <a name="aggregate_apidocs">Aggregating Java apidocs</a>
 126
 127 Javadoc is generated automatically for each bundle however to aggregate them
 128 all into a single convenient url we need to ensure that the root pom has a
 129 profile to activate it. The following should be copied into the profiles
 130 section of the project root pom.
 131
 132     <profiles>
 133       <profile>
 134         <!--
 135             This profile is to ensure we only build javadocs reports
 136             when we plan to deploy Maven site for our project.
 137         -->
 138         <id>maven-site</id>
 139         <activation>
 140           <file>
 141             <exists>${user.dir}/deploy-site.xml</exists>
 142           </file>
 143         </activation>
 144
 145         <build>
 146           <plugins>
 147             <plugin>
 148               <groupId>org.apache.maven.plugins</groupId>
 149               <artifactId>maven-javadoc-plugin</artifactId>
 150               <inherited>false</inherited>
 151               <executions>
 152                 <execution>
 153                   <id>aggregate</id>
 154                   <goals>
 155                     <goal>aggregate</goal>
 156                   </goals>
 157                   <phase>package</phase>
 158               </execution>
 159               </executions>
 160             </plugin>
 161           </plugins>
 162         </build>
 163       </profile>
 164     </profiles>