## 3.6 Project Documentation

Since Grails 1.2, the documentation engine that powers the creation of this documentation is available to your Grails 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 `grails-app/conf/Config.groovy` file that customize the output of the documentation such as:

- grails.doc.authors - The authors of the documentation
- grails.doc.license - The license of the software
- grails.doc.copyright - The copyright message to display
- grails.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:

    grails docs

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`

    @monospace@

Italic: italic

    _italic_

Bold: bold

    *bold*

Image:

    !http://grails.org/images/new/grailslogo_topNav.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:

    [SpringSource|http://www.springsource.com/] or "SpringSource":http://www.springsource.com/

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 `grails-app/conf/Config.groovy`:

    grails.doc.alias.intro="1. Introduction"

And then the link becomes:

    [Intro|guide:intro]

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:

    [controllers|renderPDF]

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 `grails-app/conf/Config.groovy`. For example:

    grails.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:

    # item 1

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:

    <hello>world</hello>

    {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}