Maven: The Complete Reference
   - 10.5. Writing Project Documentation

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

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 "[]".

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 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. FAQ Markup Language Document shows an example of an FML document.

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>











Become a Member

Are you a current user of:
Top