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 a src/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
The title of each chapter is taken from the file name. The order is dictated by the numerical value at the beginning of the file name.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 the src/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 your griffon-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
Other properties such as the name of the documentation and the version are pulled from your project itself.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:This command will output an 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
Italic: italic
Bold: bold
Image:

!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.codehaus.org/] or "Griffon":http://griffon.codehaus.org/
For links to other sections inside the user guide you can use the guide:
prefix:[Intro|guide:1. Introduction]
The documentation engine will warn you if any links to sections in your guide break. Sometimes though it is preferable not to hard code the actual names of guide sections since you may move them around. To get around this you can create an alias inside griffon-app/conf/BuildConfig.groovy
:griffon.doc.alias.intro="1. Introduction"
And then the link becomes:This is useful since if you linked the to "1. Introduction" chapter many times you would have to change all of those links.To link to reference items you can use a special syntax:In this case the category of the reference item is on the left hand side of the | and the name of the reference item on the right.Finally, to link to external APIs you can use the api:
prefix. For example:[String|api:java.lang.String]
The documentation engine will automatically create the appropriate javadoc link in this case. If you want to add additional APIs to the engine you can configure them in griffon-app/conf/BuildConfig.groovy
. For example:griffon.doc.api.org.hibernate="http://docs.jboss.org/hibernate/stable/core/api"
The above example configures classes within the 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
Unordered lists are defined with the use of the * character:* item 1
** subitem 1
** subitem 2
* item 2
Numbered lists can be defined with the # character:Tables can be created using the 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 the code
macro:class Book {
String title
}
{code}
class Book {
String title
}
{code}
The example above provides syntax highlighting for Java and Groovy code, but you can also highlight XML markup:{code:xml}
<hello>world</hello>
{code}
There are also a couple of macros for displaying notes and warnings:Note:
This is a note!
{note}
This is a note!
{note}
Warning:
This is a warning!
{warning}
This is a warning!
{warning}