This is an automated email from the ASF dual-hosted git repository.
hboutemy pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-site.git
The following commit(s) were added to refs/heads/master by this push:
new b5b8b01 [DOXIASITETOOLS-229] show doxiaVersion +
doxiaSitetoolsVersion example
b5b8b01 is described below
commit b5b8b0150a0b8a3e7a31b4d21b80a4ddeceee2e2
Author: Hervé Boutemy <[email protected]>
AuthorDate: Fri Jul 2 23:09:06 2021 +0200
[DOXIASITETOOLS-229] show doxiaVersion + doxiaSitetoolsVersion example
---
.../guide-java-report-plugin-development.apt | 390 +++++++++++----------
1 file changed, 203 insertions(+), 187 deletions(-)
diff --git a/content/apt/guides/plugin/guide-java-report-plugin-development.apt
b/content/apt/guides/plugin/guide-java-report-plugin-development.apt
index 2abcf6b..0ab1fe6 100644
--- a/content/apt/guides/plugin/guide-java-report-plugin-development.apt
+++ b/content/apt/guides/plugin/guide-java-report-plugin-development.apt
@@ -30,8 +30,8 @@
Introduction
This guide is intended to assist users in developing reporting plugins for
- Maven in Java that will contribute to sites generated by
{{{/plugins/maven-site-plugin/}<<<maven-site-plugin>>>}}
- or site pdf documents generated by
{{{/plugins/maven-pdf-plugin/}<<<maven-pdf-site>>>}}.
+ Maven in Java, that will contribute to sites generated by
{{{/plugins/maven-site-plugin/}<<<maven-site-plugin>>>}}
+ or site PDF documents generated by
{{{/plugins/maven-pdf-plugin/}<<<maven-pdf-site>>>}}.
First and foremost, a <report plugin> is a <Maven plugin> and it is strongly
advised to first read the
{{{./guide-java-plugin-development.html}Guide to Developing Java Plugins}}
to properly understand
@@ -47,7 +47,7 @@ Introduction
* How It Works
[[1]]
- A regular Maven project usually invokes a <reporting goal> of a plugin by
declaring such plugin in the
+ A regular Maven project usually invokes <reporting goals> of a plugin by
declaring such plugin in the
{{{/plugins/maven-site-plugin/examples/configuring-reports.html}<<<<reporting\>>>>}}
section of its <<<pom.xml>>> as in the example below:
+---+
@@ -67,12 +67,12 @@ Introduction
[[2]]
When {{{/plugins/maven-site-plugin/}<<<maven-site-plugin>>>}} is invoked
(for example with the <<<mvn site>>> command),
- the specified plugins are loaded and the <generate()> method of each class
that implements
-
{{{/shared/maven-reporting-api/apidocs/org/apache/maven/reporting/MavenReport.html}<MavenReport>}}
+ the specified plugins are loaded and the <<<generate()>>> method of each
Mojo class that implements
+
{{{/shared/maven-reporting-api/apidocs/org/apache/maven/reporting/MavenReport.html}<<<MavenReport>>>}}
is executed.
[[3]]
- The <generate()> method generates a document through Maven's
{{{/doxia/doxia/doxia-sink-api/}Doxia Sink API}}.
+ The <<<generate()>>> method generates a document through Maven's
{{{/doxia/doxia/doxia-sink-api/}Doxia Sink API}}.
This document is comprised of basic elements like title, headings, text,
links, tables, etc.
This is where you will put the logic of your report, assembling elements,
based on the content of the Maven project.
@@ -90,13 +90,14 @@ Introduction
* Basic Requirements of a Report <Mojo>
Each goal or <Mojo> is implemented with a separate Java class. For a <Mojo>
to become a <report Mojo>, it needs to
- implement
{{{/shared/maven-reporting-api/apidocs/org/apache/maven/reporting/MavenReport.html}<MavenReport>}}
- (in addition to
{{{/ref/current/apidocs/org/apache/maven/plugin/Mojo.html}<org.apache.maven.plugin.Mojo>}}).
- An easy way to implement both interfaces is to extend
- the
{{{/shared/maven-reporting-impl/apidocs/org/apache/maven/reporting/AbstractMavenReport.html}<org.apache.maven.reporting.AbstractMavenReport>}}
- class (instead of <org.apache.maven.plugin.AbstractMojo> for a regular
<Mojo>).
+ implement
{{{/shared/maven-reporting-api/apidocs/org/apache/maven/reporting/MavenReport.html}<<<org.apache.maven.reporting.MavenReport>>>}}
+ (in addition to
{{{/ref/current/apidocs/org/apache/maven/plugin/Mojo.html}<<<org.apache.maven.plugin.Mojo>>>}}).
- The class will also need to implement the following methods:
+ An easy way to implement both <<<Mojo>>> and <<<MavenReport>>> interfaces is
to extend
+ the
{{{/shared/maven-reporting-impl/apidocs/org/apache/maven/reporting/AbstractMavenReport.html}<<<org.apache.maven.reporting.AbstractMavenReport>>>}}
+ class provided by
{{{/shared/maven-reporting-impl/}<<<maven-reporting-impl>>>}} (instead of
<<<org.apache.maven.plugin.AbstractMojo>>> for a regular <Mojo>).
+
+ The class will need to implement the following methods:
* <<<public String getOutputName()>>>: returns the name of page that will be
produced
@@ -145,88 +146,102 @@ Introduction
+---
<project xmlns="http://maven.apache.org/POM/4.0.0";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/xsd/maven-4.0.0.xsd";>
-
- <modelVersion>4.0.0</modelVersion>
-
- <groupId>com.mycompany.maven</groupId>
- <artifactId>simple-maven-plugin</artifactId>
- <version>1.0-SNAPSHOT</version>
- <packaging>maven-plugin</packaging>
-
- <name>Simple Plugin</name>
-
- <properties>
-
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
- </properties>
-
- <dependencies>
- <!-- reporting API -->
- <dependency>
- <groupId>org.apache.maven.reporting</groupId>
- <artifactId>maven-reporting-impl</artifactId>
- <version>3.0.0</version>
- </dependency>
- <dependency>
- <groupId>org.apache.maven.reporting</groupId>
- <artifactId>maven-reporting-api</artifactId>
- <version>3.0</version>
- </dependency>
-
- <!-- plugin API and plugin-tools -->
- <dependency>
- <groupId>org.apache.maven</groupId>
- <artifactId>maven-plugin-api</artifactId>
- <version>3.5.2</version>
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/xsd/maven-4.0.0.xsd";>
+
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>com.mycompany.maven</groupId>
+ <artifactId>simple-maven-plugin</artifactId>
+ <version>1.0-SNAPSHOT</version>
+ <packaging>maven-plugin</packaging>
+
+ <name>Simple Plugin</name>
+
+ <properties>
+ <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+ <doxiaVersion>1.10</doxiaVersion>
+ <doxiaSitetoolsVersion>1.10</doxiaSitetoolsVersion>
+ </properties>
+
+ <dependencies>
+ <!-- Doxia API and Doxia Sitetools -->
+ <dependency>
+ <groupId>org.apache.maven.doxia</groupId>
+ <artifactId>doxia-sink-api</artifactId>
+ <version>${doxiaVersion}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.maven.doxia</groupId>
+ <artifactId>doxia-site-renderer</artifactId>
+ <version>${doxiaSitetoolsVersion}</version>
+ </dependency>
+
+ <!-- reporting API -->
+ <dependency>
+ <groupId>org.apache.maven.reporting</groupId>
+ <artifactId>maven-reporting-impl</artifactId>
+ <version>3.0.0</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.maven.reporting</groupId>
+ <artifactId>maven-reporting-api</artifactId>
+ <version>3.0</version>
+ </dependency>
+
+ <!-- plugin API and plugin-tools -->
+ <dependency>
+ <groupId>org.apache.maven</groupId>
+ <artifactId>maven-plugin-api</artifactId>
+ <version>3.5.2</version>
+ <scope>provided</scope>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.maven.plugin-tools</groupId>
+ <artifactId>maven-plugin-annotations</artifactId>
+ <version>3.5</version>
<scope>provided</scope>
- </dependency>
- <dependency>
- <groupId>org.apache.maven.plugin-tools</groupId>
- <artifactId>maven-plugin-annotations</artifactId>
- <version>3.5</version>
- <scope>provided</scope>
- </dependency>
- <dependency>
- <groupId>org.apache.maven.shared</groupId>
- <artifactId>maven-shared-utils</artifactId>
- <version>3.2.0</version>
- </dependency>
-
- </dependencies>
-
-
- <build>
- <plugins>
- <plugin>
- <artifactId>maven-compiler-plugin</artifactId>
- <version>3.7.0</version>
- </plugin>
- <plugin>
- <artifactId>maven-install-plugin</artifactId>
- <version>2.5.2</version>
- </plugin>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-plugin-plugin</artifactId>
- <version>3.5.1</version>
- <configuration>
- <goalPrefix>simple</goalPrefix>
- </configuration>
- <executions>
- <execution>
- <id>default-descriptor</id>
- <phase>process-classes</phase>
- </execution>
- <execution>
- <id>generated-helpmojo</id>
- <goals>
- <goal>helpmojo</goal>
- </goals>
- </execution>
- </executions>
- </plugin>
- </plugins>
- </build>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.maven.shared</groupId>
+ <artifactId>maven-shared-utils</artifactId>
+ <version>3.2.0</version>
+ </dependency>
+
+ </dependencies>
+
+
+ <build>
+ <plugins>
+ <plugin>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <version>3.7.0</version>
+ </plugin>
+ <plugin>
+ <artifactId>maven-install-plugin</artifactId>
+ <version>2.5.2</version>
+ </plugin>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-plugin-plugin</artifactId>
+ <version>3.5.1</version>
+ <configuration>
+ <goalPrefix>simple</goalPrefix>
+ </configuration>
+ <executions>
+ <execution>
+ <id>default-descriptor</id>
+ <phase>process-classes</phase>
+ </execution>
+ <execution>
+ <id>generated-helpmojo</id>
+ <goals>
+ <goal>helpmojo</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
</project>
+---
@@ -257,79 +272,79 @@ import org.apache.maven.reporting.MavenReportException;
*
*/
@Mojo(
- name = "simple",
- defaultPhase = LifecyclePhase.SITE,
- requiresDependencyResolution = ResolutionScope.RUNTIME,
- requiresProject = true,
- threadSafe = true
- )
+ name = "simple",
+ defaultPhase = LifecyclePhase.SITE,
+ requiresDependencyResolution = ResolutionScope.RUNTIME,
+ requiresProject = true,
+ threadSafe = true
+ )
public class SimpleReport extends AbstractMavenReport {
- public String getOutputName() {
- // This report will generate simple-report.html when invoked in
a project with `mvn site`
- return "simple-report";
- }
-
- public String getName(Locale locale) {
- // Name of the report when listed in the project-reports.html
page of a project
- return "Simple Report";
- }
-
- public String getDescription(Locale locale) {
- // Description of the report when listed in the
project-reports.html page of a project
- return "This simple report is a very simple report that does
nothing but "
- + "shows off Maven's wonderful reporting capabilities.";
- }
-
- /**
- * Practical reference to the Maven project
- */
- @Parameter(defaultValue = "${project}", readonly = true)
- private MavenProject project;
-
- @Override
- protected void executeReport(Locale locale) throws MavenReportException
{
-
- // Get the logger
- Log logger = getLog();
-
- // Some info
- logger.info("Generating " + getOutputName() + ".html"
- + " for " + project.getName() + " " +
project.getVersion());
-
- // Get the Maven Doxia Sink, which will be used to generate the
- // various elements of the document
- Sink mainSink = getSink();
- if (mainSink == null) {
- throw new MavenReportException("Could not get the Doxia
sink");
- }
-
- // Page title
- mainSink.head();
- mainSink.title();
- mainSink.text("Simple Report for " + project.getName() + " " +
project.getVersion());
- mainSink.title_();
- mainSink.head_();
-
- mainSink.body();
-
- // Heading 1
- mainSink.section1();
- mainSink.sectionTitle1();
- mainSink.text("Simple Report for " + project.getName() + " " +
project.getVersion());
- mainSink.sectionTitle1_();
-
- // Content
- mainSink.paragraph();
- mainSink.text("This page provides simple information, like its
location: ");
- mainSink.text(project.getBasedir().getAbsolutePath());
- mainSink.paragraph_();
-
- // Close
+ public String getOutputName() {
+ // This report will generate simple-report.html when invoked in a
project with `mvn site`
+ return "simple-report";
+ }
+
+ public String getName(Locale locale) {
+ // Name of the report when listed in the project-reports.html page of
a project
+ return "Simple Report";
+ }
+
+ public String getDescription(Locale locale) {
+ // Description of the report when listed in the project-reports.html
page of a project
+ return "This simple report is a very simple report that does nothing
but "
+ + "shows off Maven's wonderful reporting capabilities.";
+ }
+
+ /**
+ * Practical reference to the Maven project
+ */
+ @Parameter(defaultValue = "${project}", readonly = true)
+ private MavenProject project;
+
+ @Override
+ protected void executeReport(Locale locale) throws MavenReportException {
+
+ // Get the logger
+ Log logger = getLog();
+
+ // Some info
+ logger.info("Generating " + getOutputName() + ".html"
+ + " for " + project.getName() + " " + project.getVersion());
+
+ // Get the Maven Doxia Sink, which will be used to generate the
+ // various elements of the document
+ Sink mainSink = getSink();
+ if (mainSink == null) {
+ throw new MavenReportException("Could not get the Doxia sink");
+ }
+
+ // Page title
+ mainSink.head();
+ mainSink.title();
+ mainSink.text("Simple Report for " + project.getName() + " " +
project.getVersion());
+ mainSink.title_();
+ mainSink.head_();
+
+ mainSink.body();
+
+ // Heading 1
+ mainSink.section1();
+ mainSink.sectionTitle1();
+ mainSink.text("Simple Report for " + project.getName() + " " +
project.getVersion());
+ mainSink.sectionTitle1_();
+
+ // Content
+ mainSink.paragraph();
+ mainSink.text("This page provides simple information, like its
location: ");
+ mainSink.text(project.getBasedir().getAbsolutePath());
+ mainSink.paragraph_();
+
+ // Close
mainSink.section1_();
- mainSink.body_();
+ mainSink.body_();
- }
+ }
}
+---
@@ -388,17 +403,18 @@ simple:simple
+---
<project>
-...
-<reporting>
- <plugins>
- <plugin>
- <groupId>com.mycompany.maven</groupId>
- <artifactId>simple-maven-plugin</artifactId>
- <version>1.0-SNAPSHOT</version>
- </plugin>
- </plugins>
-</reporting>
-...
+ ...
+ <reporting>
+ <plugins>
+ <plugin>
+ <groupId>com.mycompany.maven</groupId>
+ <artifactId>simple-maven-plugin</artifactId>
+ <version>1.0-SNAPSHOT</version>
+ </plugin>
+ </plugins>
+ </reporting>
+ ...
+</project>
+---
Note: When no specific report is specified, all of the <Mojos> in the
plugin, that are declared as "reporting" will be executed.
@@ -409,10 +425,10 @@ simple:simple
** The Doxia Sink API
- In your <executeReport()> method, you will leverage the
{{{/doxia/doxia/doxia-sink-api/}Doxia Sink API}}
+ In your <<<executeReport()>>> method, you will leverage the
{{{/doxia/doxia/doxia-sink-api/}Doxia Sink API}}
to add elements to the report document.
- You will use the
{{{/doxia/doxia/doxia-sink-api/apidocs/org/apache/maven/doxia/sink/Sink.html}<Sink>}}
object associated to the report:
+ You will use the
{{{/doxia/doxia/doxia-sink-api/apidocs/org/apache/maven/doxia/sink/Sink.html}<<<Sink>>>}}
object associated to the report:
+---
Sink sink = getSink();
@@ -422,15 +438,15 @@ Sink sink = getSink();
you cannot insert elements in already existing elements, or remove elements.
The elements that you append to the document will look familiar if you have
basic knowledge of HTML. Most of the elements
- have opening and closing tags, like <sink.body()> (opening) and
<sink.body_()> (closing).
+ have opening and closing tags, like <<<sink.body()>>> (opening) and
<<<sink.body_()>>> (closing).
- * <sink.head()> and <sink.head_()>
+ * <<<sink.head()>>> and <<<sink.head_()>>>
- * <sink.paragraph()> and <sink.paragraph_()>
+ * <<<sink.paragraph()>>> and <<<sink.paragraph_()>>>
- * <sink.section1()> and <sink.section1_()>
+ * <<<sink.section1()>>> and <<<sink.section1_()>>>
- * <sink.bold()> and <sink.bold_()>
+ * <<<sink.bold()>>> and <<<sink.bold_()>>>
* etc.
@@ -440,15 +456,15 @@ Sink sink = getSink();
At the very least, a document should include the following:
- * Head and title (<sink.head()> and <sink.title()>)
+ * Head and title (<<<sink.head()>>> and <<<sink.title()>>>)
- * Body (<sink.body()>)
+ * Body (<<<sink.body()>>>)
- * Section 1 with title (<sink.section1()> and <sink.sectionTitle1()>)
+ * Section 1 with title (<<<sink.section1()>>> and <<<sink.sectionTitle1()>>>)
[]
- The
{{{/doxia/doxia/doxia-sink-api/apidocs/org/apache/maven/doxia/sink/Sink.html}<Sink>}}
object
+ The
{{{/doxia/doxia/doxia-sink-api/apidocs/org/apache/maven/doxia/sink/Sink.html}<<<Sink>>>}}
object
allows you to add raw text with the <rawText()> method. More precisely, it
allows you to add raw HTML code into the
document for full flexibility. However, you should limit the usage of this
method as you may add elements that are not supported
by non-HTML renderers (like
{{{/plugins/maven-pdf-plugin/}<<<maven-pdf-site>>>}}).
@@ -462,11 +478,11 @@ Sink sink = getSink();
You may need to create not just one HTML file, but several of them (like
Javadoc produces one HTML file for
each Java class). To do so, you will need to get a new <Sink> for each HTML
file you need to produce.
This is achieved by using the
-
{{{/doxia/doxia/doxia-sink-api/apidocs/org/apache/maven/doxia/sink/SinkFactory.html}<SinkFactory>}}
object
+
{{{/doxia/doxia/doxia-sink-api/apidocs/org/apache/maven/doxia/sink/SinkFactory.html}<<<SinkFactory>>>}}
object
that you can easily obtain with the
-
{{{/shared/maven-reporting-impl/apidocs/org/apache/maven/reporting/AbstractMavenReport.html#getSinkFactory()}<getSinkFactory()>}}
+
{{{/shared/maven-reporting-impl/apidocs/org/apache/maven/reporting/AbstractMavenReport.html#getSinkFactory()}<<<getSinkFactory()>>>}}
method of your
-
{{{/shared/maven-reporting-impl/apidocs/org/apache/maven/reporting/AbstractMavenReport.html}<AbstractMavenReport>}}
instance,
+
{{{/shared/maven-reporting-impl/apidocs/org/apache/maven/reporting/AbstractMavenReport.html}<<<AbstractMavenReport>>>}}
instance,
as in the example below.
+---
