10.4. Site Directory Structure  TOC  10.6. Deploying Your Project Website

10.5. Writing Project Documentation

Maven uses a documentation-processing engine called Doxia which reads multiple source formats into a common document model. Doxia can then manipulate documents and render the result into several output formats, such as PDF or XHTML. To write document for your project, you will need to write your content in a format which can be parsed by Doxia. Doxia currently has support for Almost Plain Text (APT), XDoc (a Maven 1.x documentation format), XHTML, and FML (useful for FAQ documents) formats.

This chapter has a cursory introduction to the APT format. For a deeper understand of the APT format, or for an in-depth introduction to XDoc or FML, please see the following resources:

10.5.1. APT Example

Example 10.5, “APT Document” shows a simple APT document with an introductory paragraph and a simple list. Note that the list is terminated by the psuedo-element "[]".

Example 10.5. APT Document

---
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}}
 
   []

If the APT document from Example 10.5, “APT Document” were placed in src/site/apt/index.apt, the Maven Site plugin will parse the APT using Doxia and produce XHTML content in index.html.

10.5.2. FML Example

Many projects maintain a Frequently Asked Questions (FAQ) page. Example 10.6, “FAQ Markup Language Document” shows an example of an FML document.

Example 10.6. FAQ Markup Language Document

<?xml version="1.0" encoding="UTF-8"?>
<faqs title="Frequently Asked Questions">
  <part id="General">
    <faq id="sample-project-sucks">
      <question>Sample project doesn't work.  Why does sample 
        project suck?</question>
      <answer>
        <p>
          We resent that question.  Sample wasn't designed to work, it was 
          designed to show you how to use Maven.   If you really think 
          this project sucks, then keep it to yourself.   We're not 
          interested in your pestering questions.
        </p>
      </answer>
    </faq>
    <faq id="sample-project-source">
      <question>I want to put some code in Sample Project, 
        how do I do this?</question>
      <answer>
        <p>
          If you want to add code to this project, just start putting 
          Java source in src/main/java.   If you want to put some source 
          code in this FAQ, use the source element:
        </p>
        <source>
          for( int i = 0; i < 1234; i++ ) {
            // do something brilliant
          }
        </source>
      </answer>
    </faq>
  </part>
</faqs>


Prev  Home  Next
10.4. Site Directory Structure  Sponsored by Sonatype  10.6. Deploying Your Project Website