Documenting with the Maven Site plugin

Along with the clean and default lifecycle, Maven also consists of a site lifecycle. Like clean, site is implemented by a Maven plugin, in this case, the Maven Site plugin.

Getting ready

Maven is set up on your system and is verified for work. To do this, refer to the first three recipes of Chapter 1, Getting Started.

How to do it...

Use the following steps to generate documentation using the Maven Site plugin:

  1. Open one of the Maven projects for which we need to generate a site report (for instance, project-with-documentation).
  2. Run the following command:
    mvn site
  3. Observe the output as shown in the following screenshot:
    How to do it...
  4. Open the index.html file generated in the target/site folder:
    How to do it...

How it works...

Site is one of the Maven lifecycles. When the mvn site command is run, it invokes the site phase of the site lifecycle. The site goal of the Maven Site plugin is bound to this phase and is invoked.

The site goal performs a series of steps to generate the report. It uses various elements in the pom file related to this. Let us look at the various items in the default report:

How it works...

In addition to this, the site command generates reports based on the contents of the reporting section of the pom:

<reporting>
  <plugins>
    <plugin>
      <artifactId>maven-project-info-reports-plugin</artifactId>
      <version>2.0.1</version>
      <reportSets>
        <reportSet></reportSet>
      </reportSets>
    </plugin>
  </plugins>
</reporting>

A number of Maven plugins can generate reports defined and configured under the reporting element. We will see many reports in the following sections.

There's more...

We have only seen what the default site command offers. The Maven Site plugin offers various configurations to make many more customizations. Some of them are as follows:

  • Create a different documentation format: The default format of the site is APT (almost plain text), a wiki-like format
  • Override the default navigation tree: This is required if you want to insert additional content in the site
  • Creating skins: This is needed if you want to style the site reports differently

Let us see how to do some of these:

  1. Add the site.xml file with the following content to the srcsite folder of the project-with-documentation project folder:
    <project xmlns="http://maven.apache.org/DECORATION/1.6.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/DECORATION/1.6.0 http://maven.apache.org/xsd/decoration-1.6.0.xsd" name="Project with Documentation">
    <bannerLeft>
        <name>Left Banner</name>
        <src>images/packt.png</src>
        <href>http://www.packtpub.com</href>
    </bannerLeft>
    <body>
        <menu name="Project with Documentation">
            <item name="Overview" href="EB9781785286124_3.html"/>
        </menu>
        <menu ref="reports"/>
    </body>
</project>
  2. Add the image named packt.png to the srcsite esourcesimages folder.
  3. Now, add the index.apt file in the srcsiteapt folder with the following content:
    Welcome to Project with Documentation. This is a maven project created as part of apache maven cookbook by Packt Publishing.

What is Project with Documentation?

This maven project contains examples of how to use the site feature of maven.
  4. Run the following command:
    mvn clean site
  5. View the generated site report:
    There's more...

You can see a customized site page with the logo and the content that we specified.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
3.135.247.68