java - Maven 和 JavaDoc : install additional (generated) files

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 运行的 Hook after javadoc，before ./target/foobar-0.0.1-SNAPSHOT-javadoc。 jar 构建...

Answer 1

长话短说。 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>