如何在Maven中使用插件来生成文档？代码举例讲解

发表于 作者 IT之美

在Maven中使用插件生成文档的主要步骤是:

  1. 在pom.xml中添加maven-site-plugin坐标:
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-site-plugin</artifactId>
  <version>3.9.1</version>
</plugin>
  1. 配置插件在site阶段执行:
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-site-plugin</artifactId>
  <version>3.9.1</version>
  <executions>
    <execution>
      <phase>site</phase>
      <goals>
        <goal>site</goal>  
      </goals>
    </execution>
  </executions>
</plugin>
  1. 配置site目录和生成文档类型:
<reporting>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-site-plugin</artifactId>
      <version>3.9.1</version>
      <configuration>
        <siteDirectory>${basedir}/src/site</siteDirectory>  
        <locales>zh_CN</locales> 
        <generatePom>true</generatePom>
      </configuration>
    </plugin>
  </plugins>
</reporting>
  1. 在src/site/添加文档模板或翻译文件。
  2. 执行mvn site生成文档。

Maven Site插件的主要作用是:

  1. 生成Maven项目标准文档(概览、补丁报告等)。
  2. 支持自定义模板和翻译实现文档定制。
  3. 集成其他报告如Javadoc、Rat等。
  4. 生成的文档可以发布在Maven站点或其他服务器。

下面我们来看一个简单示例:

  1. 添加Site插件坐标:
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-site-plugin</artifactId>
  <version>3.9.1</version>
</plugin>
  1. 配置插件执行和参数:
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-site-plugin</artifactId>
  <version>3.9.1</version>
  <executions>
    <execution>  
      <phase>site</phase>  
      <goals>
        <goal>site</goal>
      </goals>
    </execution>
  </executions>
  <configuration>
    <siteDirectory>${basedir}/src/site</siteDirectory>  
    <locales>zh_CN</locales>  
    <generatePom>true</generatePom>
  </configuration>
</plugin>
  1. 在src/site目录添加document.xml作为首页:
<?xml version="1.0" encoding="UTF-8"?>
<document>
<properties>    
  <title>Maven Site Demo</title>
</properties>
<body>
  <p>这是一个Maven Site插件生成的首页!</p> 
</body>
</document>
  1. 执行mvn site,在target/site生成文档站点。

所以,通过简单的Maven Site插件配置,我们实现了项目文档的自动生成,这也大大提高了项目的可读性。