Maven 3: Generate Javadoc for defined artifacts

Question

I want to generate javadocs only for certain artifacts of my project from within a dedicated docs-project.

That means that I would like to have an independent project called "docs" for example. In the docs/pom.xml I would like to define the artifacts that should be included in the generated javadocs.

So far I learned that I have to generate a separate sources.jar for the projects I want to include. But I can't figure out how to go on from there.

For now I can only imagine two approaches:

1. Get the artifacts (sources.jar) I want to include, unpack them and somehow point the Javadoc plugin to the source directory.

2. Define the artifacts I am interested as dependency and use the "dependencySourceInclude" option of the javadoc-plugin. But I am not sure if this is usage as intended.

Any suggestions how to solve this problem?

Answer 1

I have found a solution my self. It is a bit of a hack but it does work for me. I chose to go with my first idea:

Get the artifacts (sources.jar) I want to include, unpack them and somehow point the javadoc plugin to the source directory.

This solution has four differents parts which I'll explain in more detail later:

1. Generate sources.jars in all artifacts I want to include
2. Unpack those sources.jars
3. Generate Javadoc by pointing the javadoc-plugin to the unpacked sources
4. Package the generated apidocs in a zip file

Now in more detail:

1. Generate sources.jars in all artifacts I want to include

To generate sources.jars you have to use the maven-sources-plugin as follows:

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-source-plugin</artifactId>
      <version>2.1.2</version>
      <executions>
        <execution>
          <id>bundle-sources</id>
          <phase>package</phase>
          <goals>
            <goal>jar</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

You have to do this in every project/module/artifact you want to include in your apidocs.

2. Unpack those sources.jars

In you pom.xml you use to generate the javadocs you have to add the following plugins to unpack the sources.jar files.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-dependency-plugin</artifactId>
  <executions>
    <execution>
      <id>unpack-artifact-sources</id>
      <phase>generate-resources</phase>
      <goals>
        <goal>unpack</goal>
      </goals>
      <configuration>
        <artifactItems>
          <artifactItem>
            <groupId>${project.groupId}</groupId>
            <artifactId><!-- your artifact here --></artifactId>
            <version>${project.version}</version>
            <classifier>sources</classifier>
            <overWrite>true</overWrite>
          </artifactItem>
        </artifactItems>
        <outputDirectory>${project.build.directory}/unpack_sources</outputDirectory>
      </configuration>
    </execution>
    <!-- add more unpack-executions here -->
  </executions>
</plugin>

You can add as many unpack-execution-blocks as you like.

3. Generate Javadoc by pointing the javadoc-plugin to the unpacked sources

Now the tricky part. Letting the javadoc-plugin know where to look for the source files. The imported definition is the <sourcepath> definition. In this section we define the folder where we have unpacked the sources in step 2.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <version>2.7</version>
  <configuration>
    <sourcepath>${project.build.directory}/unpack_sources</sourcepath>
  </configuration>
  <executions>
    <execution>
      <goals>
        <goal>javadoc</goal>
      </goals>
      <phase>process-resources</phase>
    </execution>
  </executions>
</plugin>

When you call mvn clean install at this point you will end up with a site folder inside your target folder. In this site folder you'll find your apidocs. But to make this build all shiny and stuff we want to assemble the apidocs into a zip archive.

4. Package the generated apidocs in a zip file

To assemble the docs you have to use the maven-assembly-plugin and a extra assembly-file. First the plugin-defintion inside your pom:

<plugin>
  <artifactId>maven-assembly-plugin</artifactId>
  <executions>
    <execution>
      <id>docs-assembly</id>
      <phase>package</phase>
      <configuration>
        <appendAssemblyId>false</appendAssemblyId>
        <descriptors>
          <descriptor>src/main/assembly/assemble.xml</descriptor>
        </descriptors>
      </configuration>
      <goals>
        <goal>single</goal>
      </goals>
    </execution>
  </executions>
</plugin>

assemble.xml:

<?xml version="1.0" encoding="UTF-8"?>
<assembly>
  <id>${project.build.finalName}</id>
  <formats>
    <format>zip</format>
  </formats>
  <includeBaseDirectory>false</includeBaseDirectory>
  <fileSets>
    <fileSet>
      <directory>target/site/apidocs</directory>
      <outputDirectory>/</outputDirectory>
    </fileSet>
  </fileSets>
</assembly>