7

I do not want to have the documentation of a multi-module Maven project under site folder for Maven Site workflow. The documentation lives under project-docs with the project-parent. What's the best practice packaging for such module?

The setup is

  1. Packaging is now configured as jar
  2. There's a Maven plugin that generates HTML/PDF documentation in phase prepare-package under some directory (src/main/docs) of project-docs during build workflow.
  3. There's a default Maven assembly descriptor that generates a project-docs-NNN-default.zip.
  4. The default artifact of the project is an empty JAR file.

Regarding the (3) in above, the alternatives:

Packaging: pom

Does not support prepare-package as the probably most suitable phase. If then phase site is used, you cannot have the generated documentation inside the default install life cycle.

Packaging: jar

The empty JAR is useless!

nobeh
  • 9,784
  • 10
  • 49
  • 66
  • I would use JAR in your case, disabling the JAR plugin execution if you really do not want the empty JAR – Tome Jul 15 '14 at 07:09
  • The install life cycle is for jar or default life cycle whereas the site-deploy is for site life cycle so you could use `pre-site` for this. – khmarbaise Jul 15 '14 at 14:42

1 Answers1

3

Since you do not want to use site generation for documentation, I think there is no other "maven official way" to perform it.

Packaging

From my point of view, you may use a standard POM packaging, zip it through maven-assembly-plugin and add a classfier (doc or everything else).

related questions

Here some information to accomplish it :

Even if it's already OK, there is interesting point there.

pom.xml

<groupId>com.mycompany</groupId>
<artifactId>your-project</artifactId>
<version>1.1.0</version>

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-assembly-plugin</artifactId>
            <executions>
                <execution>
                    <id>doc-packaging</id>
                    <goals>
                        <goal>single</goal>
                    </goals>
                    <phase>package</phase>
                    <configuration>
                        <descriptors>
                            <descriptor>/src/main/assembly/doc.xml</descriptor>
                        </descriptors>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Assembly descriptor : It will produce this artifact : your-project-doc.zip :

  • this is (obviously) a zip archive
  • the "classifier" is doc (like assembly name)

Phase binding

Since pom doesn't have anything to prepare, you're right, there is no prepare-package phase (as per doc) . Indeed, your project aims to package doc ... so it would be correct to (re)bind your pdf plugin execution to package.

Community
  • 1
  • 1
Jean-Rémy Revy
  • 5,607
  • 3
  • 39
  • 65