From bfad2895e21022f3d1c94095fd18d06703afb103 Mon Sep 17 00:00:00 2001 From: Sylwester Lachiewicz Date: Thu, 6 Aug 2026 13:53:05 +0200 Subject: [PATCH 1/2] Rename the site documents ahead of converting them A pure rename, so that git records it and `git log --follow` and `git blame` still reach the history of each page after the conversion that follows. The content is still APT at this point and the site does not build between the two commits. --- .../src/site/{apt/index.apt.vm => markdown/index.md.vm} | 0 .../examples/generate-descriptor.md.vm} | 0 .../examples/generate-help.md.vm} | 0 .../examples/using-annotations.md.vm} | 0 maven-plugin-plugin/src/site/{apt/index.apt => markdown/index.md} | 0 maven-plugin-plugin/src/site/{apt/usage.apt => markdown/usage.md} | 0 .../examples/generate-report.md.vm} | 0 .../src/site/{apt/index.apt => markdown/index.md} | 0 .../src/site/{apt/usage.apt => markdown/usage.md} | 0 .../src/site/{apt/index.apt => markdown/index.md} | 0 .../src/site/{apt/index.apt => markdown/index.md} | 0 11 files changed, 0 insertions(+), 0 deletions(-) rename maven-plugin-annotations/src/site/{apt/index.apt.vm => markdown/index.md.vm} (100%) rename maven-plugin-plugin/src/site/{apt/examples/generate-descriptor.apt.vm => markdown/examples/generate-descriptor.md.vm} (100%) rename maven-plugin-plugin/src/site/{apt/examples/generate-help.apt.vm => markdown/examples/generate-help.md.vm} (100%) rename maven-plugin-plugin/src/site/{apt/examples/using-annotations.apt.vm => markdown/examples/using-annotations.md.vm} (100%) rename maven-plugin-plugin/src/site/{apt/index.apt => markdown/index.md} (100%) rename maven-plugin-plugin/src/site/{apt/usage.apt => markdown/usage.md} (100%) rename maven-plugin-report-plugin/src/site/{apt/examples/generate-report.apt.vm => markdown/examples/generate-report.md.vm} (100%) rename maven-plugin-report-plugin/src/site/{apt/index.apt => markdown/index.md} (100%) rename maven-plugin-report-plugin/src/site/{apt/usage.apt => markdown/usage.md} (100%) rename maven-plugin-tools-annotations/src/site/{apt/index.apt => markdown/index.md} (100%) rename maven-plugin-tools-api/src/site/{apt/index.apt => markdown/index.md} (100%) diff --git a/maven-plugin-annotations/src/site/apt/index.apt.vm b/maven-plugin-annotations/src/site/markdown/index.md.vm similarity index 100% rename from maven-plugin-annotations/src/site/apt/index.apt.vm rename to maven-plugin-annotations/src/site/markdown/index.md.vm diff --git a/maven-plugin-plugin/src/site/apt/examples/generate-descriptor.apt.vm b/maven-plugin-plugin/src/site/markdown/examples/generate-descriptor.md.vm similarity index 100% rename from maven-plugin-plugin/src/site/apt/examples/generate-descriptor.apt.vm rename to maven-plugin-plugin/src/site/markdown/examples/generate-descriptor.md.vm diff --git a/maven-plugin-plugin/src/site/apt/examples/generate-help.apt.vm b/maven-plugin-plugin/src/site/markdown/examples/generate-help.md.vm similarity index 100% rename from maven-plugin-plugin/src/site/apt/examples/generate-help.apt.vm rename to maven-plugin-plugin/src/site/markdown/examples/generate-help.md.vm diff --git a/maven-plugin-plugin/src/site/apt/examples/using-annotations.apt.vm b/maven-plugin-plugin/src/site/markdown/examples/using-annotations.md.vm similarity index 100% rename from maven-plugin-plugin/src/site/apt/examples/using-annotations.apt.vm rename to maven-plugin-plugin/src/site/markdown/examples/using-annotations.md.vm diff --git a/maven-plugin-plugin/src/site/apt/index.apt b/maven-plugin-plugin/src/site/markdown/index.md similarity index 100% rename from maven-plugin-plugin/src/site/apt/index.apt rename to maven-plugin-plugin/src/site/markdown/index.md diff --git a/maven-plugin-plugin/src/site/apt/usage.apt b/maven-plugin-plugin/src/site/markdown/usage.md similarity index 100% rename from maven-plugin-plugin/src/site/apt/usage.apt rename to maven-plugin-plugin/src/site/markdown/usage.md diff --git a/maven-plugin-report-plugin/src/site/apt/examples/generate-report.apt.vm b/maven-plugin-report-plugin/src/site/markdown/examples/generate-report.md.vm similarity index 100% rename from maven-plugin-report-plugin/src/site/apt/examples/generate-report.apt.vm rename to maven-plugin-report-plugin/src/site/markdown/examples/generate-report.md.vm diff --git a/maven-plugin-report-plugin/src/site/apt/index.apt b/maven-plugin-report-plugin/src/site/markdown/index.md similarity index 100% rename from maven-plugin-report-plugin/src/site/apt/index.apt rename to maven-plugin-report-plugin/src/site/markdown/index.md diff --git a/maven-plugin-report-plugin/src/site/apt/usage.apt b/maven-plugin-report-plugin/src/site/markdown/usage.md similarity index 100% rename from maven-plugin-report-plugin/src/site/apt/usage.apt rename to maven-plugin-report-plugin/src/site/markdown/usage.md diff --git a/maven-plugin-tools-annotations/src/site/apt/index.apt b/maven-plugin-tools-annotations/src/site/markdown/index.md similarity index 100% rename from maven-plugin-tools-annotations/src/site/apt/index.apt rename to maven-plugin-tools-annotations/src/site/markdown/index.md diff --git a/maven-plugin-tools-api/src/site/apt/index.apt b/maven-plugin-tools-api/src/site/markdown/index.md similarity index 100% rename from maven-plugin-tools-api/src/site/apt/index.apt rename to maven-plugin-tools-api/src/site/markdown/index.md From db98f3b918767d0c844f7221ae664445e6649305 Mon Sep 17 00:00:00 2001 From: Sylwester Lachiewicz Date: Thu, 6 Aug 2026 13:53:05 +0200 Subject: [PATCH 2/2] Port the site documentation from APT to Markdown 11 page(s) converted with doxia-converter and then cleaned up by hand: - <<>> becomes backticks, <> becomes **bold**, {{{url}text}} becomes [text](url) - the ASF license header becomes a single block HTML comment - a page whose only Velocity reference was ${project.name} is now a plain .md with the title spelled out - a page that keeps a reference stays a .vm. Velocity reads ## as a line comment and would silently swallow every ATX heading below level one, so subsections use setext underlines and anything deeper is wrapped in #[[ ... ]]# - a reference APT rendered literally is escaped with ${esc.d}, which always yields a literal dollar; a backslash only works when the reference itself resolves Verified by building the site before and after and comparing every generated page: the visible text and the link targets are unchanged apart from / becoming / and quotes and ellipses in prose picking up the Markdown module's typographic substitution. --- .../src/site/markdown/index.md.vm | 53 +++--- .../examples/generate-descriptor.md.vm | 70 +++---- .../markdown/examples/generate-help.md.vm | 51 +++-- .../markdown/examples/using-annotations.md.vm | 111 ++++------- .../src/site/markdown/index.md | 99 ++++------ .../src/site/markdown/usage.md | 104 +++++------ .../markdown/examples/generate-report.md.vm | 176 ++++++++---------- .../src/site/markdown/index.md | 81 +++----- .../src/site/markdown/usage.md | 80 ++++---- .../src/site/markdown/index.md | 91 ++++----- .../src/site/markdown/index.md | 50 ++--- 11 files changed, 388 insertions(+), 578 deletions(-) diff --git a/maven-plugin-annotations/src/site/markdown/index.md.vm b/maven-plugin-annotations/src/site/markdown/index.md.vm index dbc2ce963..099151ff4 100644 --- a/maven-plugin-annotations/src/site/markdown/index.md.vm +++ b/maven-plugin-annotations/src/site/markdown/index.md.vm @@ -1,38 +1,27 @@ - ------ - About ${project.name} - ------ - Hervé Boutemy - ------ - 2012-06-03 - ------ + -About ${project.name} +# About ${project.name} - ${project.description} +${project.description} -* Usage +Usage +----- - To be able to {{{../maven-plugin-tools-annotations/index.html}use Maven Plugin Tools Java Annotations}}, - some configuration has to be done in <<>>: see - {{{../maven-plugin-plugin/examples/using-annotations.html#POM_configuration} Using Plugin Tools Java5 Annotations}} - example in {{{../maven-plugin-plugin} <<>>}} documentation. +To be able to [use Maven Plugin Tools Java Annotations](../maven-plugin-tools-annotations/index.html), some configuration has to be done in `pom.xml`: see [ Using Plugin Tools Java5 Annotations](../maven-plugin-plugin/examples/using-annotations.html#POM_configuration) example in [ `maven-plugin-plugin`](../maven-plugin-plugin) documentation. diff --git a/maven-plugin-plugin/src/site/markdown/examples/generate-descriptor.md.vm b/maven-plugin-plugin/src/site/markdown/examples/generate-descriptor.md.vm index 83cc6bead..d1e589e33 100644 --- a/maven-plugin-plugin/src/site/markdown/examples/generate-descriptor.md.vm +++ b/maven-plugin-plugin/src/site/markdown/examples/generate-descriptor.md.vm @@ -1,36 +1,27 @@ - ------ - Configuring Generation of Plugin Descriptor - ------ - Maria Odea Ching - ------ - 2008-02-01 - ------ + -Configuring Generation of Plugin Descriptor +# Configuring Generation of Plugin Descriptor - To configure the generation of the plugin descriptor, add the following to the project's POM: +To configure the generation of the plugin descriptor, add the following to the project's POM: -+-----+ +```xml ... @@ -49,26 +40,25 @@ Configuring Generation of Plugin Descriptor ... -+-----+ +``` - The <<>> parameter will set the goal prefix for the plugin that is specified in the descriptor. The <<>> - parameter, on the other hand, specifies the target location of the generated plugin descriptor. +The `goalPrefix` parameter will set the goal prefix for the plugin that is specified in the descriptor. The `outputDirectory` parameter, on the other hand, specifies the target location of the generated plugin descriptor. -* Example +Example +------- - For instance, if we make reference on <<>> from <<>> which is generated by the - Maven Archetype Plugin, i.e.: +For instance, if we make reference on `MyMojo` from `maven-my-plugin` which is generated by the Maven Archetype Plugin, i.e.: ------ +``` mvn archetype:create \ -DgroupId=org.apache.maven.plugin.my \ -DartifactId=maven-my-plugin \ -DarchetypeArtifactId=maven-archetype-mojo ------ +``` - The plugin descriptor generated by <<>> should be: +The plugin descriptor generated by `mvn package` should be: ------ +``` org.apache.maven.plugin.my @@ -102,7 +92,7 @@ mvn archetype:create \ - \${project.build.directory} + ${esc.d}{project.build.directory} @@ -115,4 +105,4 @@ mvn archetype:create \ ------ \ No newline at end of file +``` diff --git a/maven-plugin-plugin/src/site/markdown/examples/generate-help.md.vm b/maven-plugin-plugin/src/site/markdown/examples/generate-help.md.vm index b6dfd976e..49c0f10c5 100644 --- a/maven-plugin-plugin/src/site/markdown/examples/generate-help.md.vm +++ b/maven-plugin-plugin/src/site/markdown/examples/generate-help.md.vm @@ -1,36 +1,27 @@ - ------ - Configuring Generation of Help Mojo - ------ - Vincent Siveton - ------ - 2008-01-01 - ------ + -Configuring Generation of Help Mojo +# Configuring Generation of Help Mojo - To configure the generation of a <<>> mojo, add the following to the project's POM: +To configure the generation of a `help` mojo, add the following to the project's POM: -+-----+ +```xml ... @@ -53,6 +44,6 @@ Configuring Generation of Help Mojo ... -+-----+ +``` - The mojo is generated by default in <<<$\{project.build.directory\}/generated-sources/plugin>>>. +The mojo is generated by default in `${esc.d}{project.build.directory}/generated-sources/plugin`. diff --git a/maven-plugin-plugin/src/site/markdown/examples/using-annotations.md.vm b/maven-plugin-plugin/src/site/markdown/examples/using-annotations.md.vm index ef81c29c5..e20ed68b5 100644 --- a/maven-plugin-plugin/src/site/markdown/examples/using-annotations.md.vm +++ b/maven-plugin-plugin/src/site/markdown/examples/using-annotations.md.vm @@ -1,87 +1,56 @@ - ------ - Using Plugin Tools Java5 Annotations - ------ - Olivier Lamy - ------ - 2012-05-14 - ------ + -Using Plugin Tools Java Annotations +# Using Plugin Tools Java Annotations - You can use Java annotations to generate the plugin descriptor file. +You can use Java annotations to generate the plugin descriptor file. - <> With annotations, your Mojo super class does not have to be in the same project: provided that the superclass also uses annotations, it - can now come from reactor projects or external dependencies. By default all dependencies are scanned, but this can be reduced with the <<>> - parameter. BUT as javadoc doclets are still useful for goals and parameters description, <<<@since>>> and <<<@deprecated>>>, the sources are still scanned. So if you use an external - dependency, you must still provide an artifact with sources (<<>> classifier) to provide documentation (the tooling will skip error if this artifact - sources is missing). +**NOTE** With annotations, your Mojo super class does not have to be in the same project: provided that the superclass also uses annotations, it can now come from reactor projects or external dependencies. By default all dependencies are scanned, but this can be reduced with the `mojoDependencies` parameter. BUT as javadoc doclets are still useful for goals and parameters description, `@since` and `@deprecated`, the sources are still scanned. So if you use an external dependency, you must still provide an artifact with sources (`sources` classifier) to provide documentation (the tooling will skip error if this artifact sources is missing). -* Annotations +Annotations +----------- - Information for plugin descriptor generation is specified using 4 annotations: +Information for plugin descriptor generation is specified using 4 annotations: - * 2 class level annotations: +- 2 class level annotations: + - `@Mojo`: This annotation will mark your class as a Mojo, + - `@Execute`: Used if your Mojo needs to fork a lifecycle, +- 1 field or method level annotations: + - `@Parameter`: Used to configure your Mojo parameters, +- 1 field level annotations: + - `@Component`: Used to configure injection of Plexus components or Maven context components. - * <<<@Mojo>>>: This annotation will mark your class as a Mojo, +For more information on these annotations, see the [corresponding documentation](../../maven-plugin-tools-annotations/index.html#Supported_Annotations). - * <<<@Execute>>>: Used if your Mojo needs to fork a lifecycle, +Notice that Plugin Tools Java Annotations are named after Plugin Tools Javadoc Tags with following little differences: - [] +|[Plugin Tools Javadoc Tags](../../maven-plugin-tools-java/index.html)|[Plugin Tools Java Annotation](../../maven-plugin-tools-annotations/index.html)| +|:---|:---| +|`@goal "goal-name"`|`@Mojo( name = "goal-name" )`| +|`@phase ""`|`@Mojo( defaultPhase = LifecyclePhase. )`| - * 1 field or method level annotations: +POM configuration +----------------- - * <<<@Parameter>>>: Used to configure your Mojo parameters, +To use these Java annotations, add a dependency on `maven-plugin-annotations` to your pom, preferably with `provided` scope. - [] - - * 1 field level annotations: - - * <<<@Component>>>: Used to configure injection of Plexus components or Maven context components. - - [] - - [] - - For more information on these annotations, see the - {{{../../maven-plugin-tools-annotations/index.html#Supported_Annotations}corresponding documentation}}. - - Notice that Plugin Tools Java Annotations are named after Plugin Tools Javadoc Tags - with following little differences: - -*-------------------------------+---------------+ -|| {{{../../maven-plugin-tools-java/index.html}Plugin Tools Javadoc Tags}} || {{{../../maven-plugin-tools-annotations/index.html}Plugin Tools Java Annotation}} || -*-------------------------------+---------------+ -| <<<@goal "goal-name">>> | <<<@Mojo( name = "goal-name" )>>> -*-------------------------------+---------------+ -| <<<@phase "\">>> | <<<@Mojo( defaultPhase = LifecyclePhase.\ )>>> -*-------------------------------+---------------+ - -* POM configuration - - To use these Java annotations, add a dependency on - <<>> to your pom, preferably with <<>> scope. - -+-----+ +```xml ... maven-plugin @@ -117,4 +86,4 @@ Using Plugin Tools Java Annotations ... -+-----+ +``` diff --git a/maven-plugin-plugin/src/site/markdown/index.md b/maven-plugin-plugin/src/site/markdown/index.md index 371d77347..a29eb31c3 100644 --- a/maven-plugin-plugin/src/site/markdown/index.md +++ b/maven-plugin-plugin/src/site/markdown/index.md @@ -1,79 +1,46 @@ - ------ - Introduction - ------ - Maria Odea Ching - ------ - 2008-01-01 - ------ + -Maven Plugin Plugin +# Maven Plugin Plugin - The Maven Plugin Plugin is used to create a {{{/ref/current/maven-plugin-api/plugin.html}Maven plugin descriptor}} for any - {{{/general.html#What_is_a_Mojo}Mojo}}'s found in the source tree, to include in the JAR. - It is also used to generate report files for the Mojos as well as the artifact metadata and generating a generic help goal. +The Maven Plugin Plugin is used to create a [Maven plugin descriptor](/ref/current/maven-plugin-api/plugin.html) for any [Mojo](/general.html#What_is_a_Mojo)'s found in the source tree, to include in the JAR. It is also used to generate report files for the Mojos as well as the artifact metadata and generating a generic help goal. -* Goals Overview +## Goals Overview - The Plugin Plugin has four goals: +The Plugin Plugin has four goals: - * {{{./descriptor-mojo.html}plugin:descriptor}} generates a plugin descriptor, +- [plugin:descriptor](./descriptor-mojo.html) generates a plugin descriptor, +- [plugin:addPluginArtifactMetadata](./addPluginArtifactMetadata-mojo.html) injects any plugin-specific artifact metadata to the project's artifact, for subsequent installation and deployment, +- [plugin:helpmojo](./helpmojo-mojo.html) generates a help mojo which describes all mojos in a plugin, +- [plugin:help](./help-mojo.html) display help information on maven-plugin-plugin. +## Usage - * {{{./addPluginArtifactMetadata-mojo.html}plugin:addPluginArtifactMetadata}} injects any plugin-specific artifact - metadata to the project's artifact, for subsequent installation and deployment, +General instructions on how to use the Plugin Plugin can be found on the [usage page](./usage.html). Some more specific use cases are described in the examples given below. Last but not least, users occasionally contribute additional examples, tips or errata to the [Plugin Developers Centre page](https://maven.apache.org/plugin-developers/index.html). - * {{{./helpmojo-mojo.html}plugin:helpmojo}} generates a help mojo which describes all mojos in a plugin, +In case you still have questions regarding the plugin's usage feel free to contact the [user mailing list](./mailing-lists.html). The posts to the mailing list are archived and could already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching the [mail archive](./mailing-lists.html). - * {{{./help-mojo.html}plugin:help}} display help information on maven-plugin-plugin. +If you feel like the plugin is missing a feature or has a defect, you can fill a feature request or bug report in our [issue tracker](./issue-management.html). When creating a new issue, please provide a comprehensive description of your concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason, entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated. Of course, patches are welcome, too. Contributors can check out the project from our [source repository](./scm.html) and will find supplementary information in the [guide to helping with Maven](/guides/development/guide-helping.html). - [] +## Examples -* Usage +The following examples shows how to use the Plugin Plugin in more advanced usecases: - General instructions on how to use the Plugin Plugin can be found on the {{{./usage.html}usage page}}. Some more - specific use cases are described in the examples given below. Last but not least, users occasionally contribute - additional examples, tips or errata to the - {{{https://maven.apache.org/plugin-developers/index.html}Plugin Developers Centre page}}. - - In case you still have questions regarding the plugin's usage feel free to contact the {{{./mailing-lists.html}user mailing list}}. - The posts to the mailing list are archived and could already contain the answer to your question as part of an older thread. - Hence, it is also worth browsing/searching the {{{./mailing-lists.html}mail archive}}. - - If you feel like the plugin is missing a feature or has a defect, you can fill a feature request or bug report in our - {{{./issue-management.html}issue tracker}}. When creating a new issue, please provide a comprehensive description of your - concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason, - entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated. - Of course, patches are welcome, too. Contributors can check out the project from our - {{{./scm.html}source repository}} and will find supplementary information in the - {{{/guides/development/guide-helping.html}guide to helping with Maven}}. - -* Examples - - The following examples shows how to use the Plugin Plugin in more advanced usecases: - - * {{{./examples/using-annotations.html}Using Plugin Tools Java5 annotations for your Mojo}} - - * {{{./examples/generate-descriptor.html}Configuring Generation of Plugin Descriptor}} - - * {{{./examples/generate-help.html}Configuring Generation of Help Mojo}} - - [] +- [Using Plugin Tools Java5 annotations for your Mojo](./examples/using-annotations.html) +- [Configuring Generation of Plugin Descriptor](./examples/generate-descriptor.html) +- [Configuring Generation of Help Mojo](./examples/generate-help.html) diff --git a/maven-plugin-plugin/src/site/markdown/usage.md b/maven-plugin-plugin/src/site/markdown/usage.md index c39844ace..b13f77b99 100644 --- a/maven-plugin-plugin/src/site/markdown/usage.md +++ b/maven-plugin-plugin/src/site/markdown/usage.md @@ -1,74 +1,58 @@ - ------ - Usage - ------ - Maria Odea Ching - Vincent Siveton - ------ - 2008-01-01 - ------ - -~~ 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 - -Usage - - The Plugin Plugin is generally used for Maven plugins. Its goals are bound to different phases in the build life cycle. - So when you execute a specific phase, the Plugin Plugin goals bound to it are also executed. Aside from this, each goal can - also be explicitly executed from the command line. - -* The <<>> Goal - - The <<>> goal is bound to the <<>> phase since 3.0; it was bound to <<>> phase previously. - This goal generates the plugin descriptor, which is an xml file that contains information about the plugin - (see {{{/ref/current/maven-plugin-api/plugin.html}descriptor's reference}}). - - For example, you want to create an archive of your plugin and you execute - -+-----+ + + +# Usage + +The Plugin Plugin is generally used for Maven plugins. Its goals are bound to different phases in the build life cycle. So when you execute a specific phase, the Plugin Plugin goals bound to it are also executed. Aside from this, each goal can also be explicitly executed from the command line. + +## The `plugin:descriptor` Goal + +The `plugin:descriptor` goal is bound to the `process-classes` phase since 3.0; it was bound to `generate-resources` phase previously. This goal generates the plugin descriptor, which is an xml file that contains information about the plugin (see [descriptor's reference](/ref/current/maven-plugin-api/plugin.html)). + +For example, you want to create an archive of your plugin and you execute + +```shell mvn package -+-----+ +``` - You will see that the <<>> file is generated in the <<>> directory of your project. The file is - also bundled in the generated JAR file. +You will see that the `plugin.xml` file is generated in the `target/classes/META-INF/maven` directory of your project. The file is also bundled in the generated JAR file. - To explicitly execute the <<>> goal, type the following in the command line: +To explicitly execute the `plugin:descriptor` goal, type the following in the command line: -+-----+ +```shell mvn plugin:descriptor -+-----+ +``` -* The <<>> Goal +## The `plugin:addPluginArtifactMetadata` Goal - The <<>> goal, on the other hand, is bound to the <<>> phase of the build life cycle. - This goal will add the metadata to the project artifact. To do this, execute +The `plugin:addPluginArtifactMetadata` goal, on the other hand, is bound to the `package` phase of the build life cycle. This goal will add the metadata to the project artifact. To do this, execute -+-----+ +```shell mvn package -+-----+ +``` -* The <<>> Goal +## The `plugin:helpmojo` Goal - To generate a <<>> for the mojos of your plugin, execute the following on the command line: +To generate a `HelpMojo` for the mojos of your plugin, execute the following on the command line: -+-----+ +```shell mvn plugin:helpmojo -+-----+ +``` - The mojo is generated by default in <<<$\{project.build.directory\}/generated-sources/plugin>>>. +The mojo is generated by default in `${project.build.directory}/generated-sources/plugin`. diff --git a/maven-plugin-report-plugin/src/site/markdown/examples/generate-report.md.vm b/maven-plugin-report-plugin/src/site/markdown/examples/generate-report.md.vm index 7f0e7e31a..bf19f313d 100644 --- a/maven-plugin-report-plugin/src/site/markdown/examples/generate-report.md.vm +++ b/maven-plugin-report-plugin/src/site/markdown/examples/generate-report.md.vm @@ -1,95 +1,81 @@ - ------ - Configuring Generation of Documentation Reports - ------ - Vincent Siveton - ------ - 2008-01-01 - ------ - -~~ 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 - -Configuring Generation of Documentation Reports - - To configure the generation of the documentation reports, add the following to the project's POM: - -+-----+ - - ... - - - - org.apache.maven.plugins - maven-plugin-report-plugin - ${project.version} - - - - report - - - - - - - ... - - ... - -+-----+ - -* Generate Plugin Report without duplicate execution of phase process-classes - - The standard report goal <<>> invokes separate lifecyle of <<>>. - In a CI environment you now might execute something like <<>>. - During <<>> build the standard reports will trigger <<>> again. - Depending on your build this may take some time because - stuff like <<>> or generating stubs from a WSDL will be invoked again, which may lead - to longer build times. - - As of version 3.14.0 a new report goal is defined, <<>> which will not trigger - the above phase a second time. - - Configure this in your <<>> section as follows: - -+-----+ - - ... - - - - org.apache.maven.plugins - maven-plugin-report-plugin - ${project.version} - - - - report-no-fork - - - - - - - ... - -+-----+ - - The documentation is generated by default in <<<$\{project.build.directory\}/site>>>. + + +# Configuring Generation of Documentation Reports + +To configure the generation of the documentation reports, add the following to the project's POM: + +```xml + + ... + + + + org.apache.maven.plugins + maven-plugin-report-plugin + ${project.version} + + + + report + + + + + + + ... + + ... + +``` + +Generate Plugin Report without duplicate execution of phase process-classes +--------------------------------------------------------------------------- + +The standard report goal `report` invokes separate lifecyle of `process-classes`. In a CI environment you now might execute something like `mvn clean deploy site-deploy`. During `site` build the standard reports will trigger `process-classes` again. Depending on your build this may take some time because stuff like `enforcer` or generating stubs from a WSDL will be invoked again, which may lead to longer build times. + +As of version 3.14.0 a new report goal is defined, `report-no-fork` which will not trigger the above phase a second time. + +Configure this in your `reporting` section as follows: + +```xml + + ... + + + + org.apache.maven.plugins + maven-plugin-report-plugin + ${project.version} + + + + report-no-fork + + + + + + + ... + +``` + +The documentation is generated by default in `${esc.d}{project.build.directory}/site`. diff --git a/maven-plugin-report-plugin/src/site/markdown/index.md b/maven-plugin-report-plugin/src/site/markdown/index.md index 24117bbc9..67eb91ac1 100644 --- a/maven-plugin-report-plugin/src/site/markdown/index.md +++ b/maven-plugin-report-plugin/src/site/markdown/index.md @@ -1,65 +1,42 @@ - ------ - Introduction - ------ - Maria Odea Ching - ------ - 2008-01-01 - ------ + -Maven Plugin Report Plugin +# Maven Plugin Report Plugin - The Maven Plugin Report Plugin is used to create report files for the Mojos. +The Maven Plugin Report Plugin is used to create report files for the Mojos. -* Goals Overview +## Goals Overview - The Plugin Report Plugin has two goals: +The Plugin Report Plugin has two goals: - * {{{./report-mojo.html}plugin-report:report}} which generates the plugin documentation: one overview report and documentation for each plugin's goal (mojo). +- [plugin-report:report](./report-mojo.html) which generates the plugin documentation: one overview report and documentation for each plugin's goal (mojo). +- [plugin-report:report-no-fork](./report-no-fork-mojo.html) which generates the plugin documentation: one overview report and documentation for each plugin's goal (mojo) without forking the `process-classes` phase again. Note that this goal does require generation of classes before site generation, e.g. by invoking `mvn clean verify site`. +## Usage - * {{{./report-no-fork-mojo.html}plugin-report:report-no-fork}} which generates the plugin documentation: one overview report and documentation for each plugin's goal (mojo) without forking the <<>> phase again. Note that this goal does require generation of classes before site generation, e.g. by invoking <<>>. +General instructions on how to use the Plugin Report Plugin can be found on the [usage page](./usage.html). - [] +In case you still have questions regarding the plugin's usage feel free to contact the [user mailing list](./mailing-lists.html). The posts to the mailing list are archived and could already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching the [mail archive](./mailing-lists.html). -* Usage +If you feel like the plugin is missing a feature or has a defect, you can fill a feature request or bug report in our [issue tracker](./issue-management.html). When creating a new issue, please provide a comprehensive description of your concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason, entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated. Of course, patches are welcome, too. Contributors can check out the project from our [source repository](./scm.html) and will find supplementary information in the [guide to helping with Maven](/guides/development/guide-helping.html). - General instructions on how to use the Plugin Report Plugin can be found on the {{{./usage.html}usage page}}. +## Examples - In case you still have questions regarding the plugin's usage feel free to contact the {{{./mailing-lists.html}user mailing list}}. - The posts to the mailing list are archived and could already contain the answer to your question as part of an older thread. - Hence, it is also worth browsing/searching the {{{./mailing-lists.html}mail archive}}. +The following examples shows how to use the Plugin Report Plugin in more advanced usecases: - If you feel like the plugin is missing a feature or has a defect, you can fill a feature request or bug report in our - {{{./issue-management.html}issue tracker}}. When creating a new issue, please provide a comprehensive description of your - concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason, - entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated. - Of course, patches are welcome, too. Contributors can check out the project from our - {{{./scm.html}source repository}} and will find supplementary information in the - {{{/guides/development/guide-helping.html}guide to helping with Maven}}. - -* Examples - - The following examples shows how to use the Plugin Report Plugin in more advanced usecases: - - * {{{./examples/generate-report.html}Configuring Generation of Documentation Reports}} - - [] +- [Configuring Generation of Documentation Reports](./examples/generate-report.html) diff --git a/maven-plugin-report-plugin/src/site/markdown/usage.md b/maven-plugin-report-plugin/src/site/markdown/usage.md index d53b1d2d3..fa009b882 100644 --- a/maven-plugin-report-plugin/src/site/markdown/usage.md +++ b/maven-plugin-report-plugin/src/site/markdown/usage.md @@ -1,46 +1,34 @@ - ------ - Usage - ------ - Maria Odea Ching - Vincent Siveton - ------ - 2008-01-01 - ------ - -~~ 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 - -Usage - - The Plugin Report Plugin is used to create reports about the plugin being built. - -* The <<>> Goal - - To generate the documentation of your plugin, execute the following on the command line: - -+-----+ -mvn plugin-report:report -+-----+ - - The xdoc files, one per goal, are generated by default in <<<$\{project.build.directory\}/generated-site/xdoc>>>, - and an overview is generated in the site output. - - If you add the plugin to the <<>> section of your pom, you'll get the full report as html with <<>>. - + + +# Usage + +The Plugin Report Plugin is used to create reports about the plugin being built. + +## The `plugin-report:report` Goal + +To generate the documentation of your plugin, execute the following on the command line: + +```shell +mvn plugin-report:report +``` + +The xdoc files, one per goal, are generated by default in `${project.build.directory}/generated-site/xdoc`, and an overview is generated in the site output. + +If you add the plugin to the `reporting` section of your pom, you'll get the full report as html with `mvn site`. diff --git a/maven-plugin-tools-annotations/src/site/markdown/index.md b/maven-plugin-tools-annotations/src/site/markdown/index.md index a4f156b33..83bbe3a6a 100644 --- a/maven-plugin-tools-annotations/src/site/markdown/index.md +++ b/maven-plugin-tools-annotations/src/site/markdown/index.md @@ -1,41 +1,29 @@ - ------ - Introduction - ------ - Hervé Boutemy - ------ - 2012-05-12 - ------ - -~~ 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 - -Maven Plugin Tool for Annotations - - The Maven Plugin Tool for Annotations is the <<>> implementation of - {{{../maven-plugin-tools-api/index.html}maven-plugin-tools-api}} - to extract descriptors from plugins written in Java with - {{{../maven-plugin-annotations/index.html}Maven Plugin Tools Java Annotations}}. - -* Supported Annotations - -+---------+ + + +# Maven Plugin Tool for Annotations + +The Maven Plugin Tool for Annotations is the `java-annotations` implementation of [maven-plugin-tools-api](../maven-plugin-tools-api/index.html) to extract descriptors from plugins written in Java with [Maven Plugin Tools Java Annotations](../maven-plugin-annotations/index.html). + +## Supported Annotations + +```java import org.apache.maven.execution.MavenSession; import org.apache.maven.plugin.AbstractMojo; import org.apache.maven.plugin.MojoExecution; @@ -145,23 +133,14 @@ public class MyMojo ... } } -+---------+ - - -* See also - - * {{{../maven-plugin-annotations/index.html}Maven Plugin Tools Java Annotations}} - - * {{{/developers/mojo-api-specification.html#The_Descriptor_and_Annotations}Mojo API Specification}} - - * {{{/ref/current/maven-plugin-api/plugin.html}META-INF/maven/plugin.xml plugin descriptor}} - - * {{{/ref/current/maven-core/apidocs/org/apache/maven/plugin/PluginParameterExpressionEvaluator.html}PluginParameterExpressionEvaluator}}, - used to evaluate plugin parameters values during Mojo configuration, - - * pseudo parameters: +``` - * <<>> {{{https://maven.apache.org/ref/current/maven-core/apidocs/org/apache/maven/plugin/PluginParameterExpressionEvaluator.html}javadoc}} / - {{{https://maven.apache.org/ref/current/maven-core/xref/org/apache/maven/plugin/PluginParameterExpressionEvaluator.html}source}} +## See also - * {{{https://issues.apache.org/jira/browse/MNG-5695}MNG-5695}}: scoped objects added to Guice/Sisu in {{{https://maven.apache.org/ref/current/maven-core/}maven-core}} 3.2.5 +- [Maven Plugin Tools Java Annotations](../maven-plugin-annotations/index.html) +- [Mojo API Specification](/developers/mojo-api-specification.html#The_Descriptor_and_Annotations) +- [META-INF/maven/plugin.xml plugin descriptor](/ref/current/maven-plugin-api/plugin.html) +- [PluginParameterExpressionEvaluator](/ref/current/maven-core/apidocs/org/apache/maven/plugin/PluginParameterExpressionEvaluator.html), used to evaluate plugin parameters values during Mojo configuration, +- pseudo parameters: + - `PluginParameterExpressionEvaluator` [javadoc](https://maven.apache.org/ref/current/maven-core/apidocs/org/apache/maven/plugin/PluginParameterExpressionEvaluator.html) / [source](https://maven.apache.org/ref/current/maven-core/xref/org/apache/maven/plugin/PluginParameterExpressionEvaluator.html) + - [MNG-5695](https://issues.apache.org/jira/browse/MNG-5695): scoped objects added to Guice/Sisu in [maven-core](https://maven.apache.org/ref/current/maven-core/) 3.2.5 diff --git a/maven-plugin-tools-api/src/site/markdown/index.md b/maven-plugin-tools-api/src/site/markdown/index.md index 72644a073..a4d7188b3 100644 --- a/maven-plugin-tools-api/src/site/markdown/index.md +++ b/maven-plugin-tools-api/src/site/markdown/index.md @@ -1,36 +1,26 @@ - ------ - Introduction - ------ - Vincent Siveton - ------ - 2012-05-14 - ------ + -Maven Plugin Tool API +# Maven Plugin Tool API - The Maven Plugin Tool API is the API to extract descriptors for all supported Maven plugins. +The Maven Plugin Tool API is the API to extract descriptors for all supported Maven plugins. - Main component is {{{./apidocs/org/apache/maven/tools/plugin/scanner/MojoScanner.html}MojoScanner}}. +Main component is [MojoScanner](./apidocs/org/apache/maven/tools/plugin/scanner/MojoScanner.html). - Each descriptor extractor needs to implement - {{{./apidocs/org/apache/maven/tools/plugin/extractor/MojoDescriptorExtractor.html}MojoDescriptorExtractor}}. +Each descriptor extractor needs to implement [MojoDescriptorExtractor](./apidocs/org/apache/maven/tools/plugin/extractor/MojoDescriptorExtractor.html).