Maven and JavaDoc: install additional (generated) files

Question

My project can generate some additional help files automatically from the source code.

How do I have maven install these files into the generated JavaDoc package?

I couldn't fingure out how to have Maven:

1. run some class to generate the additional documentation, e.g. compile and launch src/main/java/mypackage/ListOptions.java aka mypackage.ListOptions to produce a list of all available options/modules/examples/etc. .

2. install the output files (I only could get Maven to install files from src/main/javadoc/resources into the site/apidocs/resources subfolder; but I want this documentation to live in the top level site/apidocs folder; more precisely I don't care about the site part at all, but about having a complete documetation in mypackage-0.1.0-SNAPSHOT-javadoc.jar; including non-Javadoc-generated auxillary information linked from javadoc).

Minimal example - Plugin configuration for 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>

Directory layout:

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

mvn package produces: javadoc in ./target/apidocs and ./target/foobar-0.0.1-SNAPSHOT-javadoc.jar. The file target/apidocs/resources/insubfolder.png ends up in folder target/apidocs/resources (and the .jar), but the staticfile.js is not installed.

How to run GenerateNonstatic.java to have the output included in the javadoc .jar is unclear to me. I don't see a hook to have exec:exec it run after javadoc, and before ./target/foobar-0.0.1-SNAPSHOT-javadoc.jar is built...

Answer 1

Long story, short answer. Both the javadoc:javadoc and javadoc:jar mojos have their drawbacks. The first is meant to build the javadoc for reporting; the latter will build the javadoc (into a different directory) and produce a jar package.

Some of the suggested answers did not work well because of this - they would execute javadoc twice.

But I noticed that javadoc does not care if the folder already exists or contains files.

So my solution is simple: generate the desired additional files in prepare-package, and the regular javadoc:jar task adds the regular javadoc and pacakges it nicely.

This will work as long as you don't intend to modify files generated by javadoc (which I, fortunately, don't - I only add additional documentation.

The resulting pom.xml is like this:

<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>