Publish JavaDoc API Documentation when Releasing from Jenkins

this article describes how to publish javadoc api documentation for a maven project built on jenkins when that project is released. the javadoc api documentation is published using the same instance of apache tomcat 7 that jenkins runs on.

motivation

i wanted to, using the simplest way possible, publish javadoc api documentation for releases of a certain software component and make it available at a url unique to each version. in addition, i wanted to make the possible to list the different versions of the software component for which documentation is available.
the software component is built using maven and releases are made from a jenkins server.

required jenkins plug-ins

the following plug-ins need to be installed in jenkins in order to be able to complete the example in this article:

• the appropriate plug-in for the source code management system you use.
  in this article i will use git, but any other source code management system works equally well as long as there is a jenkins plug-in available for it.
• maven project plug-in.
  enables the creation of maven 2/3 jobs in jenkins.
• jenkins m2 release plug-in
  also know as the maven release plug-in, which enables the performing of maven releases from a jenkins job.

prepare apache tomcat

the following steps prepares a special web application, the documentation web application, in apache tomcat 7 to which javadoc api documentation will be published. it is assumed that the directory containing the web applications deployed to tomcat resides in the webapps directory in the tomcat installation directory.

• in the webapps directory in the tomcat home directory, create a directory for the documentation web application.
  in this example, i name my directory “api-documentation”, but you are of course free to choose any name you find appropriate.
• in the documentation web application directory, create a web-inf directory.
• in the web-inf directory created in the previous step, create a file named “web.xml”.
  the resulting directory structure should look like in the following picture:

• paste the following into the web.xml file created in the previous step:

<?xml version="1.0" encoding="iso-8859-1"?>
<!--
    configures the default servlet to allow directory listings for the
    documentation web application.
-->
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/xmlschema-instance"
  xsi:schemalocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
  version="3.0">
    <servlet>
        <servlet-name>default</servlet-name>
        <servlet-class>org.apache.catalina.servlets.defaultservlet</servlet-class>
        <init-param>
            <param-name>debug</param-name>
            <param-value>0</param-value>
        </init-param>
        <init-param>
            <param-name>listings</param-name>
            <param-value>true</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <!--
        start of security configuration.
        this section can be removed if no security is required for api documentation.
    -->
    <security-constraint>
        <web-resource-collection>
            <web-resource-name>api documentation root</web-resource-name>
            <url-pattern>/*</url-pattern>
        </web-resource-collection>
        <auth-constraint>
            <!--
                this role must be present in the tomcat-users.xml file.
                the username and password to enter when accessing api documentation is the
                username and password of any user belonging to this role.
            -->
            <role-name>manager-gui</role-name>
        </auth-constraint>
    </security-constraint>

    <login-config>
        <auth-method>basic</auth-method>
        <realm-name>api documentation</realm-name>
    </login-config>

    <security-role>
        <description>the role that is required to access the api documentation</description>
        <!--
            this role must be present in the tomcat-users.xml file.
            the username and password to enter when accessing api documentation is the
            username and password of any user belonging to this role.
        -->
        <role-name>manager-gui</role-name>
    </security-role>
    <!-- end of security configuration. -->
</web-app>

the above web application configuration file configures the tomcat default servlet to allow directory listings. since the configuration file is located in a specific web application, directory listings will only be allowed in that particular web application.
in addition, security is configured, requiring login before being able to view api documentation. note that the role specified in the element must be defined in the tomcat-users.xml file. removing the indicated security configuration section removes security constraints for api documentation.

please refer to the web.xml file in the conf directory in the apache tomcat 7 directory for information on the different configuration alternatives available for the default servlet.

configure the maven project

assuming that the software component for which i want to publish javadoc api documentation for already is a maven project, i still need to ensure the following:

• javadoc api documentation is created for the software component.
• the javadoc api documentation is created at the correct location to allow for deployment by the maven site plug-in.
  that is, i want the documentation to be located in the site directory in the target directory of the maven project, not directly under the target directory of the project.
• documentation is not published in by every build.
  since i only want to preserve documentation for release builds, i need to be able to control when documentation is published.
• documentation is published to the appropriate location.
  i expect that i want to publish javadoc api documentation for multiple software components in the future. i also want to be able to publish documentation for different versions of a software component.

the following maven pom.xml file contains configuration to create and publish javadoc. parts not relevant to the creation of documentation have been omitted.

<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">

    ...

    <!--
        determines to which repository releases of the project are deployed.
        in this example, artifacts are deployed to a directory on the
        same computer on which the jenkins build server is run.
        note that this is just the minimal configuration required in order
        to be able to perform a maven release, not recommended for production.
        reference: http://maven.apache.org/pom.html#distribution_management
    -->
    <distributionmanagement>
        <repository>
            <uniqueversion>false</uniqueversion>
            <id>home1</id>
            <name>home repository</name>
            <url>file://c:/myprojectdeploydirectory/</url>
            <layout>default</layout>
        </repository>
    </distributionmanagement>

    <!--
        scm configuration is necessary in order to enable maven to manage
        the version of the project when releasing a new version on the
        jenkins build server.
        the configuration varies depending on which provider is used
        (for example, git, subversion, etc).
        in this example, git is used.
        reference: http://maven.apache.org/pom.html#scm
    -->
    <scm>
       <connection>scm:git:file://localhost/c:/gitrepo/myproject/</connection>
       <developerconnection>scm:git:file://localhost/c:/gitrepo/myproject/</developerconnection>
       <tag>head</tag>
    </scm>

    <properties>
        <!--
            path to the root directory of the documentation web application.
            this example assumes that the documentation web application
            is located in the same tomcat instance as the jenkins build
            server runs.
        -->
        <release.javadoc.root.path>[path to tomcat home]/webapps/api-documentation/</release.javadoc.root.path>

        ...
    </properties>

    ...

    <profiles>
        <!--
            profile for generation and publishing of release javadoc
            documentation.
            use: mvn -p releasedocumentation site
            references: http://maven.apache.org/guides/introduction/introduction-to-profiles.html
        -->
        <profile>
            <!-- 
                name of the maven build profile.
                used in project's jenkins job configuration.
            -->
            <id>releasedocumentation</id>
            <build>
                <plugins>
                    <!--
                        in preparation of site generation, extract the release
                        version number to a maven property.
                        performed during pre-site phase.
                    -->
                    <plugin>
                        <groupid>org.codehaus.mojo</groupid>
                        <artifactid>build-helper-maven-plugin</artifactid>
                        <version>1.8</version>
                        <executions>
                            <execution>
                                <phase>pre-site</phase>
                                <id>regex-property</id>
                                <goals>
                                    <goal>regex-property</goal>
                                </goals>
                                <configuration>
                                    <name>release_version</name>
                                    <value>${project.version}</value>
                                    <regex>-snapshot</regex>
                                    <replacement />
                                    <failifnomatch>false</failifnomatch>
                                </configuration>
                            </execution>
                        </executions>
                    </plugin>
                    <!--
                        javadoc generation.
                        javadoc is generated during pre-site phase.
                    -->
                    <plugin>
                        <groupid>org.apache.maven.plugins</groupid>
                        <artifactid>maven-javadoc-plugin</artifactid>
                        <version>2.9.1</version>
                        <executions>
                            <execution>
                                <phase>pre-site</phase>
                                <goals>
                                    <goal>javadoc</goal>
                                </goals>
                            </execution>
                        </executions>
                        <configuration>
                            <show>private</show>
                        </configuration>
                    </plugin>
                    <!--
                        copy javadoc to publish directory.
                        performed during the site phase.
                        if changing the phase, make sure that copying the
                        documentation is performed after having generated
                        the javadoc.
                    -->
                    <plugin>
                        <groupid>org.apache.maven.plugins</groupid>
                        <artifactid>maven-resources-plugin</artifactid>
                        <version>2.6</version>
                        <executions>
                            <execution>
                                <id>copy-resources</id>
                                <phase>site</phase>
                                <goals>
                                    <goal>copy-resources</goal>
                                </goals>
                                <configuration>
                                    <generateprojectinfo>false</generateprojectinfo>
                                    <generatereports>false</generatereports>
                                    <outputdirectory>${release.javadoc.root.path}${project.artifactid}-${release_version}/</outputdirectory>
                                    <resources>
                                        <resource>
                                            <directory>${project.build.directory}/site/</directory>
                                            <filtering>true</filtering>
                                        </resource>
                                    </resources>
                                </configuration>
                            </execution>
                        </executions>
                    </plugin>
                </plugins>
            </build>
            <!--
                include this section to disable, or configure, generation
                of project info report(s).
                in this case, all project info reports have been disabled.
            -->
            <reporting>
                <plugins>
                    <plugin>
                        <groupid>org.apache.maven.plugins</groupid>
                        <artifactid>maven-project-info-reports-plugin</artifactid>
                        <version>2.7</version>
                        <reportsets>
                            <reportset>
                                <reports>
                                </reports>
                            </reportset>
                        </reportsets>
                    </plugin>
                </plugins>
            </reporting>
        </profile>
    </profiles>
</project>

note that:

• the element is required, in order for maven to know to which repository to deploy project artifacts when performing a release.
  this example shows a minimal configuration, using a local directory as target, which is not recommended for production.
• it is not possible to use the element to specify where to publish the documentation, since this configuration is evaluated before we are able to set maven properties using the maven build helper plug-in.
• the element specifies where the project is located in the source-code management system.
  this configuration is necessary, in order for maven to be able to update the project version number when performing a release. this configuration depends on the source-code management system used (example: subversion, git, perforce etc).
  in this example, the git source-code management system is used with the git repository residing in a local directory.
• in the <properties> element, a maven property named “release.javadoc.root.path” is defined.
  this property specifies the local directory to which release javadoc documentation will be copied. the string “[path to tomcat home]” needs to be replaced with the path to the tomcat installation directory, or the directory that contains the webapps directory used by tomcat if it is not present in the tomcat directory.
• in the <profiles> element, a maven build profile named “releasedocumentation” is defined.
  this is the maven build profile that determines what happens when release javadoc documentation is to be produced and published.
• the first plug-in in this profile is the maven build helper plug-in.
  it is used to remove the “-snaphot” part of the version number of the software component and store the result in the maven property “release_version”.
  it is difficult to intercept the workings of the maven release plug-in at a stage where the release version number is available, so this strategy was chosen to keep the maven configuration simpler.
• the maven build helper plug-in is configured to execute during the maven pre-site phase.
  this in order to be part of the maven site goal which we will use to create and publish the javadoc documentation.
• the maven javadoc plug-in is used to generate the javadoc.
  no surprise here, except that the execution phase is set to pre-site. as with the maven build helper plug-in, in order to be part of the maven site goal which we will use to create and publish the javadoc documentation.
• the maven resources plug-in is used to copy (publish) the javadoc documentation to the api-documentation web application in tomcat.
  this plug-in will execute during the maven site phase. the site phase executes after the pre-site phase and this ensures that the javadoc has been created and that the maven “release_version” property has been set.

to generate and publish javadoc documentation for the software component, we can now issue the following command:

mvn -p releasedocumentation site

configure the jenkins job

to generate and publish documentation as part of a maven release performed in jenkins, we need to include the above maven property and goal in the release goals of the jenkins job for the software component.
in my case the build environment section of the job configuration looks like this:

remember to save the job configuration after you have made the changes!

view project javadoc

now when i perform a maven release from jenkins, the documentation is published and i can browse the documentation available for the different software components and their different versions by opening the url http://localhost:8080/api-documentation/ in my browser and then drill down into the appropriate directory.

on the first page you will see a list of the projects and versions for which javadoc have been published:

click the link for the project and version which javadoc you want to view. in my example i click the link for version 1.0.5 of the jmsrequestreply project:

click the “apidocs” link to view the javadoc.