Maven 和 JavaDoc：安装附加（生成）文件

Question

我的项目可以从源代码自动生成一些额外的帮助文件。

如何让 maven 将这些文件安装到生成的 JavaDoc 包中？

我不知道如何使用 Maven：

1. 运行一些类来生成附加文档，例如编译并启动 src/main/java/mypackage/ListOptions.java aka mypackage.ListOptions 以生成所有可用选项/模块/示例/等的列表。 .

2. 安装输出文件（我只能让 Maven 将文件从 src/main/javadoc/resources 安装到 site/apidocs/resources 子文件夹中；但我希望此文档位于顶级 site/apidocs 文件夹中；更准确地说，我不'根本不关心site 部分，而是关心mypackage-0.1.0-SNAPSHOT-javadoc.jar 中的完整文档；包括从javadoc 链接的非Javadoc 生成的辅助信息）。

最小示例 - maven 的插件配置：

        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>2.9.1</version>
            <executions>
                <execution>
                    <id>attach-javadocs</id>
                    <goals>
                        <goal>jar</goal>
                    </goals>
                </execution>
            </executions>
            <configuration>
                <docfilessubdirs>true</docfilessubdirs>
            </configuration>
        </plugin>

目录布局：

./pom.xml
./src/main/java/foobar/GenerateNonstatic.java
./src/main/javadoc/staticfile.js
./src/main/javadoc/resources/insubfolder.png

mvn package 生成：./target/apidocs 和 ./target/foobar-0.0.1-SNAPSHOT-javadoc.jar 中的 javadoc。文件target/apidocs/resources/insubfolder.png 最终位于文件夹target/apidocs/resources（和.jar）中，但未安装staticfile.js。

我不清楚如何运行 GenerateNonstatic.java 以将输出包含在 javadoc .jar 中。我没有看到让 exec:exec 它运行 after javadoc 的钩子，并且 before ./target/foobar-0.0.1-SNAPSHOT-javadoc.jar 已构建...

Answer 1

埃里克，

如果您不喜欢修改 javadoc 可执行文件，另一种选择是将您的 javadoc 调用分解为 2 个单独的步骤（javadoc 和 jar），并通过 <phase> 标签操纵 Maven 构建生命周期在它们之间进行调用：

• 阶段：生成源 => maven-javadoc-plugin:javadoc
• 阶段：编译 => exec-maven-plugin:java
• 阶段：包 => maven-javadoc-plugin:jar

注意：使用 exec:java，而不是 exec:exec 来运行 java 类

    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>2.9.1</version>
        <executions>
            <execution>
                <id>generate-javadocs</id>
                <phase>generate-sources</phase>
                <goals>
                    <goal>javadoc</goal>
                </goals>
            </execution>
            <execution>
                <id>attach-javadocs</id>
                <phase>package</phase>
                <goals>
                    <goal>jar</goal>
                </goals>
            </execution>
        </executions>
    </plugin>

    <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>exec-maven-plugin</artifactId>
        <version>1.3.2</version>
        <executions>
            <execution>
                <id>generate-nonstatic-javadocs</id>
                <phase>compile</phase>
                <goals>
                    <goal>java</goal>
                </goals>
                <configuration>
                    <mainClass>foobar.GenerateNonstatic</mainClass>
                </configuration>
            </execution>
       </executions>
    </plugin>

Answer 2

长话短说。 javadoc:javadoc 和 javadoc:jar mojos 都有其缺点。第一个是构建用于报告的 javadoc；后者将构建 javadoc（到不同的目录）并生成一个 jar 包。

因此，一些建议的答案效果不佳 - 他们会执行 javadoc 两次。

但我注意到 javadoc 并不关心文件夹是否已经存在或包含文件。

所以我的解决方案很简单：在prepare-package 中生成所需的附加文件，常规的javadoc:jar 任务添加常规的javadoc 并很好地打包它。

只要您不打算修改 javadoc 生成的文件（幸运的是，我不这样做 - 我只是添加额外的文档。

生成的pom.xml 是这样的：

<plugins>
    <!-- copy additional javadoc resources -->
    <plugin>
        <artifactId>maven-resources-plugin</artifactId>
        <version>2.7</version>
        <executions>
        <execution>
            <id>copy-resources</id>
            <phase>prepare-package</phase>
            <goals>
                <goal>copy-resources</goal>
            </goals>
            <configuration>
        <outputDirectory>${project.build.directory}/apidocs</outputDirectory>
            <resources>
            <resource>
                <directory>${basedir}/src/main/javadoc</directory>
                <excludes>
                <!-- overview.html is integrated by javadoc -->
                <exclude>${basedir}/src/main/javadoc/overview.html</exclude>
                </excludes>
            </resource>
            </resources>
            </configuration>
        </execution>
        </executions>
    </plugin>
    <!-- Generate additional files for javadoc -->
    <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>exec-maven-plugin</artifactId>
        <version>1.3.2</version>
        <executions>
            <execution>
                <id>generate-extra-javadoc</id>
                <phase>prepare-package</phase>
                <goals>
                       <!-- java is okay, but you only can have one -->
                    <goal>exec</goal>
                </goals>
                <configuration>...</configuration>
            </execution>
        </executions>
    </plugin>
    <!-- Build JavaDoc -->
    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>2.10.1</version>
        <executions>
            <execution>
                <id>attach-javadocs</id>
                <phase>package</phase>
                <goals>
                    <goal>jar</goal>
                </goals>
            </execution>
        </executions>
    </plugin>

Answer 3

回答您的第一个问题：使用 Exec-Maven-Plugin 运行命令行命令或使用 Maven-Ant-Plugin 并嵌入自定义任务。

Answer 4

埃里克，

你的例子确实很有帮助。请务必在提问时尽可能多地提供具体示例。

最简单的方法是编写自己的Alternate Javadoc tool 并通过<javadocExecutable> 标签将其传递给Maven。这个例子来自上面的链接：

<project>
  ...
  <reporting> (or <build>)
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>2.10.1</version>
        <configuration>
          <javadocExecutable>C:\jdk1.6.0\bin\javadoc.exe</javadocExecutable>
          ...
        </configuration>
      </plugin>
      ...
    </plugins>
  </reporting> (or </build>)
  ...
</project>

希望对您有所帮助。