15.5. 编写项目文档

Maven使用一个叫做Doxia的文档处理引擎,它读取多个资源格式至一个一般的文档模型。Doxia之后就可以处理文档并渲染结果至不同的输出格式,如PDF或者XHTML。要编写你项目的文档,你需要基于能被Doxia解析的格式编写内容。Doxia现在支持Almost Plain Text (APT), XDoc (一种Maven1的文档格式), XHTML, 和 FML (对FAQ文档很有用) 格式。

本章粗略的介绍一下APT格式。要深入了解APT格式,或者XDoc和FML的深入介绍,请访问如下资源:

15.5.1. APT样例

Example 15.5, “APT文档”展示了一个简单的APT文档,它带有一段介绍文字和一个简单列表。注意列表通过伪元素“[]”结束。

Example 15.5. APT文档

---
Introduction to Sample Project
---
Brian Fox
---
26-Mar-2008
---
 
Welcome to Sample Project
 
  This is a sample project, welcome!   We're excited that you've decided to read the
  index page of this Sample Project.  We hope you enjoy the simple sample project
  we've assembled for you.
 
  Here are some useful links to get you started:
 
   * {{{news.html}News}}
 
   * {{{features.html}Features}}
 
   * {{{faq.html}FAQ}}
 
   []

如果Example 15.5, “APT文档”中的APT文档位于src/site/apt/index.apt,Maven Site插件就会使用Doxia解析该APT,生成对应于index.htmlXHTML文档。