Maven Site & Reporting

The same bare POM as a parent with two modules, where tidepool-engine depends on tidepool-model, and no <reporting> configuration, fails on a clean tree. mvn clean site on Maven 3.10.0:

(The reactor lines and the error were filtered with grep, and the elapsed times are from the first run.) The site phase does not run compile or package, so the sibling module has no JAR or target/classes for the reactor to hand to tidepool-engine, and Maven looks for it in Central. Maven 3.9.16 reports the same problem as Could not find artifact io.tidepool:tidepool-model:jar:1.0.0-SNAPSHOT, and Maven 4.0.0-rc-7 adds a longer explanation about remote repository filtering. The Maven 3.10.0 wording ("NOT allowed from central") is the Resolver 2 prefix filter, which refuses to ask Central for a group path Central does not have.

Two things make the build pass. Run a lifecycle phase that produces the classes or the artifacts before the site, such as mvn package site (compile site also worked on Maven 3.10.0), or configure a report that forks the compile phase. The aggregate Javadoc and JXR reports of the parent below do: their log lines say Preparing maven-javadoc-plugin:aggregate report requires 'compile' forked phase execution. That is why the full example project builds with a plain mvn clean site once they are in the POM (run on all three Maven versions). mvn package site on the bare project:

Source: Site Plugin usage: Generating a site

Maven does not interpolate ${project.version} in a plain Markdown file. In the example, index.md contained the sentence Built from version ${project.version}. and rendered it as it is:

Renaming the file to index.md.vm makes Doxia run it through Velocity first, and the same sentence became <p>Built from version 1.0.0-SNAPSHOT.</p>. Velocity treats $ and # followed by a letter or a brace (#set, #if) as syntax, so a Markdown heading with # followed by a space is fine but a dollar amount or a #set in the text has to be escaped. The descriptor site.xml is interpolated without the .vm suffix: it may use ${project.name}, ${project.organization.name} and any property or environment variable.

Source: Maven guide: Creating a site

Source: Doxia markup language references

A child project inherits its parent’s descriptor, but not everything. The descriptor of tidepool-engine, printed by mvn -pl tidepool-engine site:effective-site on Maven 3.10.0 (comments and blank lines removed):

The skin and the <links> came from the parent, and the parent’s Tidepool menu did not: menus are not inherited unless the menu carries inherit="top" or inherit="bottom". Links and breadcrumbs accumulate. When the parent is not in the same checkout, for example a company parent POM that was installed, the child only sees its descriptor if the parent attached it, because in Maven 3 the descriptor is not an artifact by itself. The example parent does so with an execution of site:attach-descriptor:

mvn -N install on the parent then printed (the second Installing line is the descriptor):

Source: Site Plugin: Building multi-module sites, Inheritance

The Site Plugin 4.0.0-M16 is a milestone for the Maven 4 era and is the version Maven resolves when you call a goal by its prefix on a project that does not pin the plugin. It uses a newer Doxia Sitetools than the stable 3.22.0, and the skins have to match. The example project with the Site Plugin set to 4.0.0-M16 on Maven 4.0.0-rc-7 and the Fluido skin 2.1.0:

The skin asks for Doxia Sitetools 2.0.0 and the milestone plugin ships 2.0.0-M19. Stay on 3.22.0 and Fluido 2.1.0 for now, or use a skin release built for the milestone. The same hazard exists on Maven 3.10.0: on the unpinned bare POM, mvn site used site:3.22.0 through the lifecycle, while mvn site:site resolved the newest release in the plugin metadata and printed --- site:4.0.0-M16:site (default-cli). The two ways to run the "same" goal used two different plugin versions. Pinning the plugin in pluginManagement fixes both.

Source: Site Plugin: History

A plugin listed in <reporting> without <reportSets> runs every reporting goal it has, once. A <reportSet> chooses the goals, and gives them an <id> and an <inherited> flag, and optionally its own <configuration>. This is the pattern for plugins that have aggregate reports (Javadoc, JXR, Checkstyle, SpotBugs, Surefire Report and JaCoCo): the per-module report in a set that is inherited, the aggregate report in a set with <inherited>false</inherited>, so that only the parent runs it. The beginning of the reporting section of the example project, with the project-info reports and Javadoc:

Without the project-info reportSets the plugin runs all of its 16 reports, as the bare run above showed (Detected 16 reports: ci-management, dependencies, dependency-convergence, dependency-info, dependency-management, distribution-management, index, issue-management, licenses, mailing-lists, modules, plugin-management, plugins, scm, summary and team). dependency-convergence and modules are the slow or noisy ones, and the About report (index) is the one that the hand-written home page replaces.

A plugin without reportSets that has aggregate goals runs them in every module: the Site Plugin documentation warns about exactly that. SpotBugs without a reportSets was listed as Detected 2 reports for spotbugs-maven-plugin:4.10.5.0: spotbugs, spotbugs-aggregate.

Source: Site Plugin: Configuring reports

Source: POM reference: Report Sets

All of them were run on Maven 3.10.0 in the example project and produced the files shown. Each module’s site is in <module>/target/site; the parent’s is in target/site.

After mvn clean verify site, the log of the engine module (filtered with grep to the report lines) lists them in the order the plugins appear in the POM, project-info first and the two Site Plugin pages (project-info.html and project-reports.html, the index of generated reports) last:

(Only one line per plugin of the 23 Generating lines is shown, which is why the count does not match.)

The Surefire Report Plugin renders the XML files of target/surefire-reports. Use the report-only goal in <reporting>: the report goal runs the tests again. The aggregate version is report-only with the parameter aggregate set to true in a report set of the parent that is not inherited. Both sets write a file named surefire.html by default and the second one is skipped, so give the aggregate a different outputName. This is the set from the example POM:

With the same outputName the log of the first attempt said (from the debug run, -X, filtered):

The aggregate has a second trap: mvn verify site builds the parent’s site before the modules have run their tests, because Maven runs all goals of the command line for one project before the next one. The parent’s surefire-aggregate.html then reports 0 tests. Running the build in two steps, mvn clean verify and then mvn site, filled it, with the result Tests 2, Errors 0, Failures 0, Skipped 0, Success Rate 100%. The second command succeeded without install, on Maven 3.9.16, 3.10.0 and 4.0.0-rc-7: the modules' JARs from the verify run are still in their target directories and the reactor finds them. Reports that work from source (Javadoc, JXR, Checkstyle) do not have the problem.

Source: Surefire Report plugin: report-only

The JaCoCo agent has to be attached to the test JVM before the report can exist. prepare-agent sets the argLine property that Surefire passes to the forked JVM (an argLine of your own has to include @{argLine}, see Testing with Surefire); the example parent binds it for every module:

The agent writes target/jacoco.exec; the report goal in <reporting> turns it into target/site/jacoco/. In a module without that file the report says so and is skipped:

(This was printed for the parent, which has no tests.) report-aggregate sums the coverage of the dependencies of the project that runs it, not of its child modules, so running it in the parent of a multi-module build gives an empty report. The standard layout adds a module that depends on the modules to be measured and runs the aggregate goal there. In the example, tidepool-coverage has packaging pom, depends on tidepool-model and tidepool-engine, and its reporting section is:

It is built after its dependencies, so mvn verify site works in one command. The log of that module:

The report page for the two modules showed a total of 72 missed of 200 instructions (64 percent), tidepool-engine 60 percent and tidepool-model 75 percent.

A report only shows numbers; the build keeps passing. To fail the build under a threshold, use the check goal in <build>. The rule below requires 80 percent of instructions per bundle. On the example it failed in tidepool-model, whose single test covers little (mvn verify, Maven 3.10.0, JDK 21):

(The first two lines of the same execution for the parent, which has no tests, said Skipping JaCoCo execution due to missing execution data file.) The same split exists for the static-analysis plugins below: checkstyle:check, pmd:check and spotbugs:check are build goals that fail, the report goals only draw pages. The Spring Boot page Maven Quality Plugins for Spring Boot shows the check variants and the report aggregation module in more detail.

Source: JaCoCo Maven plugin

Source: JaCoCo: jacoco:prepare-agent

Source: JaCoCo: jacoco:check

Source: JaCoCo: jacoco:report-aggregate

-Dmaven.site.skip=true skips the Site Plugin’s site goal (maven.site.skip = true: Skipping site generation in the log) and -DgenerateReports=false renders only the content documents. -DgenerateProjectInfo=false leaves out project-info.html and -DgenerateSitemap=true adds sitemap.html. The reports have their own skip properties (maven.javadoc.skip for Javadoc, for example).

mvn -pl tidepool-model -Dport=8097 site:run started Jetty and rendered pages only when they were requested:

(The port parameter defaults to 8080 and host to localhost; the lines were filtered and shortened.) A request for /summary.html returned 200 with the page of the tidepool-model summary, and /index.html returned 404 because that module has no index page. The documentation states that site:run works only for single-module sites; preview a whole multi-module site with site:stage.

site:stage copies each module’s site below a staging root and appends the module’s artifact id, so the relative links between the parent and the module sites work (mvn site leaves each module’s site in its own target/site, where those links are broken). It needs a generated site first. After mvn clean verify, mvn site site:stage on Maven 3.10.0 printed one stage line per module and produced this tree in target/staging of the parent:

(The listing was cut.) The staging directory is target/staging; -DstagingDirectory=... changes it and cannot contain a dynamic expression. Stage-deploy publishes the same layout to a remote staging URL with site:stage-deploy.

On Maven 3.10.0 a goal-only mvn site:stage (no site before it) once failed with the same tidepool-engine dependency error as the bare mvn site earlier, so the examples run it as site site:stage after a verify.

site:deploy uploads target/site of each module to the URL in distributionManagement/site. In a multi-module build the modules append their artifact id, so file:///work/site/deploy/tidepool was the target for the parent and .../tidepool-model for the model. mvn clean verify site-deploy runs site, then deploy per module:

The rules of the multi-module site, from the Site Plugin guide: the topmost distributionManagement URL is the root of the tree, every module’s URL must be under it, and when a module directory name differs from its artifactId the URL must be set in that module.

The built-in protocols are file:, http(s): and dav+http(s):. Anything else, including scp:, needs a Wagon provider. With the URL of distributionManagement/site set to scp://www.example.org/www/docs/tidepool/ and no provider, mvn site site:deploy generated the site and then failed:

The fix from the Site Plugin documentation is a Wagon provider as a dependency of the plugin, here for scp and sftp (not run here: there is no SSH server to deploy to, and the build would try to connect to the host in the URL):

The <id> of the <site> element selects the <server> in settings.xml that carries the user name and key or password (see settings.xml & Password Encryption). The destination of site:stage-deploy looks up the server stagingSite when the site has no id. Source for the protocols:

Source: Site Plugin: Adding a protocol to deploy the site

Source: Site Plugin usage: Staging a site

A Git host serves a site from a branch. Deploying with Wagon would commit file by file, so the Site Plugin documentation points at the Maven SCM Publish Plugin, which commits the whole staged site once. Two steps, as the Maven guide describes: stage the site (mvn site site:stage), then mvn scm-publish:publish-scm. The plugin configuration of the example, with a local bare Git repository standing in for the GitHub repository (the guide uses ${project.scm.developerConnection} and the branch gh-pages):

mvn -N site site:stage scm-publish:publish-scm cloned the gh-pages branch of that scratch repository, copied the staged site into it, committed and pushed (filtered):

The branch in the scratch repository then had two commits (78f0444 Scratch seed and fbc1422 Site checkin for project Tidepool) and the site at its root. The 53 additions are the files of the staged parent site, and the single delete is the seed file that was not part of it. Pushing to a real GitHub repository and the GitHub Pages setting that serves the branch were not run here; the plugin needs a remote with write access and the user credentials of the SCM, and a pipeline normally uses a token. The branch must exist before the first publish (the plugin clones it). A site on GitHub Pages is a static site, so a .nojekyll file at the root stops GitHub from processing it with Jekyll, which would hide directories that start with an underscore.

Source: Maven guide: GitHub Pages and svnpubsub/gitpubsub deployment

Source: SCM Publish plugin: scm-publish:publish-scm

mvn site site:jar packs the generated site into a JAR next to the project’s own artifact. On Maven 3.10.0 for tidepool-model that printed Building jar: /work/site/fp/tidepool-model/target/tidepool-model-1.0.0-SNAPSHOT-site.jar. The JAR is a separate file; the site descriptor is attached and installed by site:attach-descriptor, shown above.

Source: Site Plugin: site:jar