mardi 11 septembre 2007

Aggrégation de Javadoc sous Maven2

Message fort intéressant sur comment aggreger simplement la javadoc sous Maven2 en utilisant les options de javadoc : 



Following some recent post about javadoc aggregation, I tried to play with javadoc attachments and dependency unpacking with some success and it was quite easy. Here are the poms:

  • For project exporting javadoc:


  • <?xml version="1.0"?><project>
    <parent>
    <artifactId>merging-javadoc</artifactId>
    <groupId>oqube.maven</groupId>
    <version>1.0-SNAPSHOT</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>
    <groupId>oqube.maven.javadoc</groupId>
    <artifactId>project1</artifactId>
    <version>1.0-SNAPSHOT</version>
    <build>
    <plugins>
    <plugin>
    <artifactId>maven-javadoc-plugin</artifactId>
    <executions>
    <execution>
    <id>attach-javadocs</id>
    <goals>
    <goal>jar</goal>
    </goals>
    </execution>
    </executions>
    </plugin>
    </plugins>
    </build>
    </project>


  • For project importing javadoc:



  • <?xml version="1.0"?><project>
    <parent>
    <artifactId>merging-javadoc</artifactId>
    <groupId>oqube.maven</groupId>
    <version>1.0-SNAPSHOT</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>
    <groupId>oqube.maven.javadoc</groupId>
    <artifactId>aggregate</artifactId>
    <version>1.0-SNAPSHOT</version>
    <build>
    <plugins>
    <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-dependency-plugin</artifactId>
    <executions>
    <execution>
    <id>unpack</id>
    <phase>package</phase>
    <goals>
    <goal>unpack</goal>
    </goals>
    <configuration>
    <artifactItems>
    <artifactItem>
    <groupId>oqube.maven.javadoc</groupId>
    <artifactId>project1</artifactId>
    <version>1.0-SNAPSHOT</version>
    <type>jar</type>
    <classifier>javadoc</classifier>
    <overWrite>true</overWrite>
    <outputDirectory>
    ${project.build.directory}/site/project1-docs/
    </outputDirectory>
    </artifactItem>
    <artifactItem>
    <groupId>oqube.maven.javadoc</groupId>
    <artifactId>project2</artifactId>
    <version>1.0-SNAPSHOT</version>
    <classifier>javadoc</classifier>
    <type>jar</type>
    <overWrite>true</overWrite>
    <outputDirectory>
    ${project.build.directory}/site/project2-docs/
    </outputDirectory>
    </artifactItem>
    </artifactItems>
    <outputDirectory>
    ${project.build.directory}/site/project2-docs/
    </outputDirectory>

    </configuration>
    </execution>
    </executions>
    </plugin>
    </plugins>
    </build>
    </project>

  • It is then just a matter of adding links on site.xml:


  • <?xml version="1.0" encoding="ISO-8859-1"?>
    <project name="Javadoc aggregation test">
    <publishDate position="bottom" format="dd-MM-yyyy"/>
    <body>
    <menu name="API Documentation">
    <item name="Project1" href="/project1-docs/index.html"/>
    <item name="Project2" href="/project2-docs/index.html"/>
    </menu>
    </body>
    </project>


Of course, this is not **true** aggregation, but it works fine. One could achieve true aggregation using similar technique but with:

  • exporting sources

  • unpackgin source files and tweaking javadoc plugin to use these as inputs