runoops.com

Maven 项目文档

本章节我们主要学习如何创建 Maven 项目文档。

比如我们在 E:/MVN 目录下,创建了 runoops 项目,Maven 使用下面的命令来快速创建 java 项目:

mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=runoops -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false

修改 pom.xml,添加以下配置(如果没有的话,1.4已经有此项配置):

<project>
  ...
<build>
<pluginManagement>
    <plugins>
        ...

         <plugin>
          <artifactId>maven-site-plugin</artifactId>
          <version>3.7.1</version>
        </plugin>
        <plugin>
          <artifactId>maven-project-info-reports-plugin</artifactId>
          <version>3.0.0</version>
        </plugin>
    </plugins>
    </pluginManagement>
</build>
 ...
</project>
mvn site 命令时出现 java.lang.NoClassDefFoundError: org/apache/maven/doxia/siterenderer/DocumentContent 的问题, 这是由于 maven-site-plugin 版本过低,升级到 3.3+ 即可。

打开 runoops 文件夹并执行以下 mvn 命令。

E:\MVN\runoops> mvn site

Maven 开始生成文档:

[INFO] Scanning for projects...
[INFO] -------------------------------------------------------------------
[INFO] Building runoops
[INFO]task-segment: [site]
[INFO] -------------------------------------------------------------------
[INFO] [site:site {execution: default-site}]
[INFO] artifact org.apache.maven.skins:maven-default-skin: 
...
...
[INFO] Generating "Plugins" report       --- maven-project-info-reports-plugin:3.0.0:plugins
[INFO] Generating "Summary" report       --- maven-project-info-reports-plugin:3.0.0:summary
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  07:45 min
[INFO] Finished at: 2022-07-15T15:10:14+08:00
[INFO] ------------------------------------------------------------------------

生成的文件结构如下:

打开 E:\MVN\runoops\target\site 文件夹。点击 index.html 就可以看到文档了。

Maven 使用一个名为 Doxia的文档处理引擎来创建文档,它能将多种格式的源码读取成一种通用的文档模型。要为你的项目撰写文档,你可以将内容写成下面几种常用的,可被 Doxia 转化的格式。

格式名描述参考
Apt纯文本文档格式http://maven.apache.org/doxia/references/apt-format.html
XdocMaven 1.x 的一种文档格式http://jakarta.apache.org/site/jakarta-site2.html
FMLFAQ 文档适用http://maven.apache.org/doxia/references/fml-format.html
XHTML可扩展的 HTML 文档http://en.wikipedia.org/wiki/XHTML