support for aggregate maven site reports

[nfalco79]

Maven plugin does not support aggregate report as javadoc. I'm trying to generate a maven multi-module site but after the site site:deploy goals index.html of enunciate 2.2.x site subfolder are always empty.

[stoicflame]

Can you share the output of "mvn -X"? We probably just need the parts of the output with "[ENUNCIATE]" in them.

[nfalco79]

This is a maven structure example. With the enunciate 1.29 build did not fail. There was not an aggregation of documentation like javadoc. With 2.2.0 build fail on parent project aggregate-parent.zip

[nfalco79]

With enunciate-maven-plugin in the build section of parent project and commenting line 294 of DocsModule (throw the exception if no resources/services/downloads are present) build process continue. All bundle has a own enunciate site in the target folder. Maven site does not have links.

To have the link to the documentation in the maven site, I must also add enunciate-maven-plugin in the reporting section of parent pom. Site was generated for each module like before but index.html is an empty file, maybe overwritted by the reporting phase.

[stoicflame]

Okay, at 65d8568, the build no longer fails if there is nothing to document.

Is there anything else that is needed for this issue to be closed? The "parent" pom doesn't generate any documentation because there are no classes to document in the parent pom (all the classes are in the submodules). Was there another expectation?

[nfalco79]

The aggregate concept is that each module site produce a specific documentation (as enunciate just do) but the report of parent it's the sum of all Web Service API produced for himself and each of its modules. Generally you could want the documentation of the entire product instead each single module documented. Going in the deept it is like enunciate execute the assemble goal instead docs goal when included in the reporting section of pom.xml. For example maven javadoc/jxr/checkstyles plugins support reportset and we could setup them to be run only on project of packing of kind pom to avoids wasting time doing the documentation twice (for himself and each of its modules). This link explains the concept in better way.

Please have a look the attached project using you actual master. example-aggregate.zip

Build it with mvn clean package site site:stage using default profile it generates javadoc as follow (see under target/staging folder):

• Parent have a Javadocs link under Project Reports that contains javadocs of:
  • Person class
  • PersonResource class
• JAXB module have a Javadocs link under Project Reports that contains javadocs of:
  • Person class
• JAX-RS module have a Javadocs link under Project Reports that contains javadocs of:
  • PersonResource class

If you build it with mvn clean package site site:stage -P only-aggregate uses the only-aggregate profile where is enable documentation only for parent and generates javadoc as follow:

• Parent have a Javadocs link under Project Reports that contains javadocs of:
  • Person class
  • PersonResource class
• JAXB module has no link under Project Reports
• JAX-RS module has no link under Project Reports

[stoicflame]

Okay, I understand what you're asking for now. Thanks for taking the time to explain.

I have spent some time looking into the javadoc plugin to see how they pulled it off, and it's going to be a lot of work to have Enunciate support aggregate reports. I acknowledge the value in the enhancement, but I think I'm going to wait to do the work until I either perceive more demand for it or someone pays for commercial support for it. Of course, I'm always open to take a look at pull requests if someone else wants to take it on.

In the meantime, I'll leave this issue open as an enhancement request and allow more people to voice their support for it.

[nfalco79]

A tricks to do a specific aggreation Mojo (like javadoc) that produces the usual documentation in the parent pom but using reactors project (field annotated ${reactorProjects}) as dependencies.

A parent pom has packaging of type pom (excluded by ConfigMojo). It has not source of bin folder. As for modules that generate documentation also for transitive dependencies with the same groupId, a parent project could consider (add) reactor projects as its direct dependency so the documentation it's an aggregation of builded modules and implement source-include filter not based on groupId but if project it's a reactor project.