diff --git a/src/site/apt/index.apt.vm b/src/site/apt/index.apt.vm deleted file mode 100644 index bac93fe..0000000 --- a/src/site/apt/index.apt.vm +++ /dev/null @@ -1,109 +0,0 @@ - ----- - Introduction - ----- - Hervé Boutemy - ----- - 2013-07-24 - ----- - - ~~ Licensed to the Apache Software Foundation (ASF) under one - ~~ or more contributor license agreements. See the NOTICE file - ~~ distributed with this work for additional information - ~~ regarding copyright ownership. The ASF licenses this file - ~~ to you under the Apache License, Version 2.0 (the - ~~ "License"); you may not use this file except in compliance - ~~ with the License. You may obtain a copy of the License at - ~~ - ~~ http://www.apache.org/licenses/LICENSE-2.0 - ~~ - ~~ Unless required by applicable law or agreed to in writing, - ~~ software distributed under the License is distributed on an - ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - ~~ KIND, either express or implied. See the License for the - ~~ specific language governing permissions and limitations - ~~ under the License. - - ~~ NOTE: For help with the syntax of this file, see: - ~~ http://maven.apache.org/doxia/references/apt-format.html - -${project.name} - - Classes to prepare report plugins execution with Maven 3, through - {{{./apidocs/org/apache/maven/reporting/exec/MavenReportExecutor.html}MavenReportExecutor}} - ({{{./apidocs/org/apache/maven/reporting/exec/DefaultMavenReportExecutor.html}implementation}}). - - Contrary to Maven 2.x: - - [[1]] report <<<\>>> explicit definition is optional:\ - if no version is specified for a report plugin, version is determined by - - [[1]] searching for the plugin in the <<>> section of the pom, - - [[2]] searching for the plugin in the <<>> section of the pom, - - [[3]] asking {{{/ref/current/maven-core/apidocs/org/apache/maven/plugin/version/PluginVersionResolver.html}PluginVersionResolver}} - to get a fallback version and display a warning as it's not a recommended use, - - [] - - [[2]] plugin configuration from <<>> is injected into <<>> - (since Maven Reporting Executor 1.2, which is {{{/plugins/maven-site-plugin/history.html}used by Maven Site Plugin 3.4}}). - - [] - -* Notice on now obsolete reportPlugin format - - Since 1.4 (used by Maven Site Plugin 3.7), the request can (and should) be populated from - {{{/ref/current/maven-model/maven.html#class_reporting}pom's <<<\>>> section}}, - injected in Mojo parameter as <<<$\{project.reporting.plugins\}>>> default value: - -+----+ - @Parameter( defaultValue = "${esc.d}{project.reporting.plugins}", readonly = true ) - private org.apache.maven.model.ReportPlugin[] reportingPlugins; -+----+ - - This section is kept to explain what happened in previous releases of the component, but this approach has been - abandonned so far after discovering major limitations: see - {{{/plugins-archives/maven-site-plugin-3.9.0/maven-3.html#New_Configuration_Maven_3_only_no_reports_configuration_inheritance}Maven Site Plugin 3.9.0 documentation}} - for more details. - - Report plugins can be configured in <<<\>>> element of <<>> or any other - report building plugin with following XML model corresponding to plugin's - <<>>> parameter: - -+----+ - - - - - - - - - - - - - - - - -+----+ - - Notice this is the model from plugins in - {{{/ref/current/maven-model/maven.html#class_reporting}<<<\>>> section of POM}}: - - * without <<<\>>> element: reporting plugins configuration inheritance is not supported at this level - (see {{{https://issues.apache.org/jira/browse/MSITE-484}MSITE-484}}), - - * with additional <<<\>>> list outside <<<\>>> that simplifies reports configuration in usual cases. - - [] - - Maven 3 core makes an automatic transformation of <<<\>>> POM section (which supports configuration inheritance) - to <<>>'s <<>> configuration through the - {{{/ref/current/maven-model-builder/apidocs/org/apache/maven/model/plugin/ReportingConverter.html}ReportingConverter}} - component. - - But Maven 3 does not do the same job for any other plugin wanting to use reports, like <<>> for example: - this is one of the key limitations that made Maven team drop this approach. diff --git a/src/site/markdown/index.md.vm b/src/site/markdown/index.md.vm new file mode 100644 index 0000000..c790fc1 --- /dev/null +++ b/src/site/markdown/index.md.vm @@ -0,0 +1,73 @@ + + +# ${project.name} + +Classes to prepare report plugins execution with Maven 3, through [MavenReportExecutor](./apidocs/org/apache/maven/reporting/exec/MavenReportExecutor.html) ([implementation](./apidocs/org/apache/maven/reporting/exec/DefaultMavenReportExecutor.html)). + +Contrary to Maven 2.x: + +1. report `` explicit definition is optional: + if no version is specified for a report plugin, version is determined by + 1. searching for the plugin in the `build/plugins` section of the pom, + 1. searching for the plugin in the `build/pluginManagement` section of the pom, + 1. asking [PluginVersionResolver](/ref/current/maven-core/apidocs/org/apache/maven/plugin/version/PluginVersionResolver.html) to get a fallback version and display a warning as it's not a recommended use, +1. plugin configuration from `build/pluginManagement` is injected into `reporting/plugins` (since Maven Reporting Executor 1.2, which is [used by Maven Site Plugin 3.4](/plugins/maven-site-plugin/history.html)). + +Notice on now obsolete reportPlugin format +------------------------------------------ + +Since 1.4 (used by Maven Site Plugin 3.7), the request can (and should) be populated from [pom's `` section](/ref/current/maven-model/maven.html#class_reporting), injected in Mojo parameter as `${esc.d}{project.reporting.plugins}` default value: + +```unknown + @Parameter( defaultValue = "${esc.d}{project.reporting.plugins}", readonly = true ) + private org.apache.maven.model.ReportPlugin[] reportingPlugins; +``` + +This section is kept to explain what happened in previous releases of the component, but this approach has been abandonned so far after discovering major limitations: see [Maven Site Plugin 3.9.0 documentation](/plugins-archives/maven-site-plugin-3.9.0/maven-3.html#New_Configuration_Maven_3_only_no_reports_configuration_inheritance) for more details. + +Report plugins can be configured in `` element of `maven-site-plugin` or any other report building plugin with following XML model corresponding to plugin's `List<`[`ReportPlugin`](./apidocs/org/apache/maven/reporting/exec/ReportPlugin.html)`>` parameter: + +```unknown + + + + + + + + + + + + + + + + +``` + +Notice this is the model from plugins in [`` section of POM](/ref/current/maven-model/maven.html#class_reporting): + +- without `` element: reporting plugins configuration inheritance is not supported at this level (see [MSITE-484](https://issues.apache.org/jira/browse/MSITE-484)), +- with additional `` list outside `` that simplifies reports configuration in usual cases. + +Maven 3 core makes an automatic transformation of `` POM section (which supports configuration inheritance) to `maven-site-plugin`'s `reportPlugins` configuration through the [ReportingConverter](/ref/current/maven-model-builder/apidocs/org/apache/maven/model/plugin/ReportingConverter.html) component. + +But Maven 3 does not do the same job for any other plugin wanting to use reports, like `maven-pdf-plugin` for example: this is one of the key limitations that made Maven team drop this approach.