3.6 Project Documentation - Reference Documentation
Authors: Andres Almiray
Version: 1.2.0
3.6 Project Documentation
Since Griffon 0.9, the documentation engine that powers the creation of this documentation is available to your Griffon projects.The documentation engine uses a variation on the Textile syntax to automatically create project documentation with smart linking, formatting etc.Creating project documentation
To use the engine you need to follow a few conventions. Firstly you need to create asrc/docs/guide
directory and then have numbered text files using the gdoc
format. For example:+ src/docs/guide/1. Introduction.gdoc + src/docs/guide/2. Getting Started.gdoc
Creating reference items
Reference items appear in the left menu on the documentation and are useful for quick reference documentation. Each reference item belongs to a category and a category is a directory located in thesrc/docs/ref
directory. For example say you defined a new method called renderPDF
, that belongs to a category called Controllers
this can be done by creating a gdoc text file at the following location:+ src/ref/Controllers/renderPDF.gdoc
Configuring Output Properties
There are various properties you can set within yourgriffon-app/conf/BuildConfig.groovy
file that customize the output of the documentation such as:
- griffon.doc.authors - The authors of the documentation
- griffon.doc.license - The license of the software
- griffon.doc.copyright - The copyright message to display
- griffon.doc.footer - The footer to use
Generating Documentation
Once you have created some documentation (refer to the syntax guide in the next chapter) you can generate an HTML version of the documentation using the command:griffon doc
docs/manual/index.html
which can be opened to view your documentation.
Documentation Syntax
As mentioned the syntax is largely similar to Textile or Confluence style wiki markup. The following sections walk you through the syntax basics.Basic Formatting
Monospace:monospace
@monospace@
_italic_
*bold*

!http://dist.codehaus.org/griffon/media/griffon.png!
Linking
There are several ways to create links with the documentation generator. A basic external link can either be defined using confluence or textile style markup:[Griffon|http://griffon-framework.org/] or "Griffon":http://griffon-framework.org/
guide:
prefix:[Intro|guide:1. Introduction]
griffon-app/conf/BuildConfig.groovy
:griffon.doc.alias.intro="1. Introduction"
[Intro|guide:intro]
[controllers|renderPDF]
api:
prefix. For example:[String|api:java.lang.String]
griffon-app/conf/BuildConfig.groovy
. For example:griffon.doc.api.org.hibernate="http://docs.jboss.org/hibernate/stable/core/api"
org.hibernate
package to link to the Hibernate website's API docs.Lists and Headings
Headings can be created by specifying the letter 'h' followed by a number and then a dot:h3.<space>Heading3 h4.<space>Heading4
* item 1 ** subitem 1 ** subitem 2 * item 2
# item 1
table
macro:Name | Number |
---|---|
Albert | 46 |
Wilma | 1348 |
James | 12 |
{table}
*Name* | *Number*
Albert | 46
Wilma | 1348
James | 12
{table}
Code and Notes
You can define code blocks with thecode
macro:class Book {
String title
}
{code}
class Book {
String title
}
{code}
<hello>world</hello>
{code:xml} <hello>world</hello> {code}
This is a note!
{note} This is a note! {note}
This is a warning!
{warning} This is a warning! {warning}