| ------ |
| Aggregating Javadocs for Multi-Projects |
| ------ |
| Maria Odea Ching |
| Vincent Siveton |
| ------ |
| 2009-08-04 |
| ------ |
| |
| ~~ Licensed to the Apache Software Foundation (ASF) under one |
| ~~ or more contributor license agreements. See the NOTICE file |
| ~~ distributed with this work for additional information |
| ~~ regarding copyright ownership. The ASF licenses this file |
| ~~ to you under the Apache License, Version 2.0 (the |
| ~~ "License"); you may not use this file except in compliance |
| ~~ with the License. You may obtain a copy of the License at |
| ~~ |
| ~~ http://www.apache.org/licenses/LICENSE-2.0 |
| ~~ |
| ~~ Unless required by applicable law or agreed to in writing, |
| ~~ software distributed under the License is distributed on an |
| ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| ~~ KIND, either express or implied. See the License for the |
| ~~ specific language governing permissions and limitations |
| ~~ under the License. |
| |
| ~~ NOTE: For help with the syntax of this file, see: |
| ~~ http://maven.apache.org/doxia/references/apt-format.html |
| |
| Aggregating Javadocs For Multi-Projects |
| |
| For example, consider the following directory structure: |
| |
| +-----+ |
| |
| Project |
| |-- pom.xml |
| |-- Module1 |
| | `-- pom.xml |
| | `-- Module 2 |
| | `-- pom.xml |
| | `-- Module 3 |
| | `-- pom.xml |
| |-- Module4 |
| | `-- pom.xml |
| `-- Module5 |
| `-- pom.xml |
| |
| +-----+ |
| |
| * Using The \<aggregate/\> Parameter (<<deprecated>>) |
| |
| <<Note>>: {{{../javadoc-mojo.html#aggregate}\<aggregate/\>}} parameter is <<deprecated>> since 2.5. Please use the |
| <<<aggregate>>> goal instead of. |
| |
| The {{{../javadoc-mojo.html#aggregate}\<aggregate/\>}} parameter can be used to generate javadocs for multi-module |
| projects. It gives the option to generate one javadoc report for the entire project (all modules) or generate one |
| javadoc report for each module. Since 3.1.0 the <<<aggregate>>> has changed a little bit. It'll generate aggregated |
| reports at every level. |
| To get only an aggregated project at root level, you need to configure the pom like: |
| |
| +-----+ |
| <project> |
| ... |
| <reporting> |
| <plugins> |
| <plugin> |
| <groupId>org.apache.maven.plugins</groupId> |
| <artifactId>maven-javadoc-plugin</artifactId> |
| <version>${project.version}</version> |
| <reportSets> |
| <reportSet> |
| <id>aggregate</id> |
| <inherited>false</inherited> |
| <reports> |
| <report>aggregate</report> |
| </reports> |
| </reportSet> |
| <reportSet> |
| <id>default</id> |
| <reports> |
| <report>javadoc</report> |
| </reports> |
| </reportSet> |
| </reportSets> |
| </plugin> |
| </plugins> |
| ... |
| </reporting> |
| ... |
| </project> |
| +-----+ |
| |
| When you execute javadoc:javadoc from Project directory with aggregate set to <<true>>, a javadoc report will be created |
| in the target directory of Project with all the javadocs of Project's modules included. If aggregate is |
| set to <<false>> (default), a javadoc report for Module1 will be generated in the target directory of Module1, a javadoc |
| report for Module2 will be generated in the target directory of Module2, and a javadoc report for Module3 will be |
| generated in the target directory of Module3. |
| |
| +-----+ |
| <project> |
| ... |
| <reporting> (or <build>) |
| <plugins> |
| <plugin> |
| <groupId>org.apache.maven.plugins</groupId> |
| <artifactId>maven-javadoc-plugin</artifactId> |
| <version>${project.version}</version> |
| <configuration> |
| ... |
| <aggregate>true</aggregate> |
| ... |
| </configuration> |
| </plugin> |
| </plugins> |
| ... |
| </reporting> (or </build>) |
| ... |
| </project> |
| +-----+ |
| |
| * Using The <<<aggregate>>> Goals |
| |
| The {{{../javadoc-mojo.html#aggregate}\<aggregate/\>}} parameter doesn't include generate source directories defined |
| using the {{{http://mojo.codehaus.org/build-helper-maven-plugin/add-source-mojo.html}build-helper:add-source}}. In |
| this case, you need to use the <<<aggregate>>> goal and <<<test-aggregate>>> goals. You could define these goals in the |
| \<build/\> element (using the \<execution/\> tag) or \<reporting/\> element (using the \<reportSet/\> tag) as shown |
| below. For more information, refer to the {{{./selective-javadocs-report.html}Selective Javadocs Reports page}}. |
| |
| +-----+ |
| <project> |
| ... |
| <build> |
| <plugins> |
| <plugin> |
| <groupId>org.apache.maven.plugins</groupId> |
| <artifactId>maven-javadoc-plugin</artifactId> |
| <version>${project.version}</version> |
| <configuration> |
| <!-- Default configuration for all reports --> |
| ... |
| </configuration> |
| <executions> |
| <execution> |
| <id>aggregate</id> |
| <goals> |
| <goal>aggregate</goal> |
| </goals> |
| <phase>site</phase> |
| <configuration> |
| <!-- Specific configuration for the aggregate report --> |
| ... |
| </configuration> |
| </execution> |
| ... |
| </executions> |
| </plugin> |
| ... |
| </plugins> |
| </build> |
| ... |
| </project> |
| +-----+ |
| |
| +-----+ |
| |
| <project> |
| ... |
| <reporting> |
| <plugins> |
| <plugin> |
| <groupId>org.apache.maven.plugins</groupId> |
| <artifactId>maven-javadoc-plugin</artifactId> |
| <version>${project.version}</version> |
| <configuration> |
| <!-- Default configuration for all reports --> |
| ... |
| </configuration> |
| <reportSets> |
| <reportSet> |
| <id>non-aggregate</id> |
| <configuration> |
| <!-- Specific configuration for the non aggregate report --> |
| ... |
| </configuration> |
| <reports> |
| <report>javadoc</report> |
| </reports> |
| </reportSet> |
| <reportSet> |
| <id>aggregate</id> |
| <configuration> |
| <!-- Specific configuration for the aggregate report --> |
| ... |
| </configuration> |
| <reports> |
| <report>aggregate</report> |
| </reports> |
| </reportSet> |
| ... |
| </reportSets> |
| </plugin> |
| ... |
| </plugins> |
| </reporting> |
| ... |
| </project> |
| +-----+ |
| |
| The Javadoc plugin contains several <<<aggregate>>> goals to be use with an aggregator project. Here is the full list |
| of all <<<aggregate>>> goals: |
| |
| * {{{../aggregate-mojo.html}javadoc:aggregate}} to generate the Javadoc files. |
| |
| * {{{../test-aggregate-mojo.html}javadoc:test-aggregate}} to generate the test Javadoc files. |
| |
| * {{{../aggregate-jar-mojo.html}javadoc:aggregate-jar}} to create an archive file of the Javadoc files. |
| |
| * {{{../test-aggregate-jar-mojo.html}javadoc:test-aggregate-jar}} to create an archive file of the test Javadoc files. |
| |
| [] |