4.6 Project Documentation 3.0.10

See the light - agile, industrial strength, rapid web application development made easy

(Quick Reference) # 4.6 Project Documentation - Reference Documentation Authors: Graeme Rocher, Peter Ledbrook, Marc Palmer, Jeff Brown, Luke Daley, Burt Beckwith, Lari Hotari Version: 3.0.10 ## 4.6 Project Documentation Since Grails 1.2, the documentation engine that powers the creation of this documentation has been available for your own 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. First, you need to create a `src/docs/guide` directory where your documentation source files will go. Then, you need to create the source docs themselves. Each chapter should have its own gdoc file as should all numbered sub-sections. You will end up with something like:
    + src/docs/guide/introduction.gdoc
    + src/docs/guide/introduction/changes.gdoc
    + src/docs/guide/gettingStarted.gdoc
    + src/docs/guide/configuration.gdoc
    + src/docs/guide/configuration/build.gdoc
    + src/docs/guide/configuration/build/controllers.gdoc
Note that you can have all your gdoc files in the top-level directory if you want, but you can also put sub-sections in sub-directories named after the parent section - as the above example shows. Once you have your source files, you still need to tell the documentation engine what the structure of your user guide is going to be. To do that, you add a `src/docs/guide/toc.yml` file that contains the structure and titles for each section. This file is in YAML format and basically represents the structure of the user guide in tree form. For example, the above files could be represented as:
    introduction:
      title: Introduction
      changes: Change Log
    gettingStarted: Getting Started
    configuration:
      title: Configuration
      build:
        title: Build Config
        controllers: Specifying Controllers
The format is pretty straightforward. Any section that has sub-sections is represented with the corresponding filename (minus the .gdoc extension) followed by a colon. The next line should contain `title:` plus the title of the section as seen by the end user. Every sub-section then has its own line after the title. Leaf nodes, i.e. those without any sub-sections, declare their title on the same line as the section name but after the colon. That's it. You can easily add, remove, and move sections within the `toc.yml` to restructure the generated user guide. You should also make sure that all section names, i.e. the gdoc filenames, should be unique since they are used for creating internal links and for the HTML filenames. Don't worry though, the documentation engine will warn you of duplicate section names. #### Creating reference items Reference items appear in the Quick Reference section of the documentation. Each reference item belongs to a category and a category is a directory located in the `src/docs/ref` directory. For example, suppose you have defined a new controller method called `renderPDF`. That belongs to the `Controllers` category so you would create a gdoc text file at the following location:
    + src/docs/ref/Controllers/renderPDF.gdoc
#### Configuring Output Properties There are various properties you can set within your `grails-app/conf/application.groovy` file that customize the output of the documentation such as: grails.doc.title - The title of the documentation grails.doc.subtitle - The subtitle of the documentation 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 version are pulled from your project itself. If a title is not specified, the application name is used. You can also customise the look of the documentation and provide images by setting a few other options: grails.doc.css - The location of a directory containing custom CSS files (type `java.io.File`) grails.doc.js - The location of a directory containing custom JavaScript files (type `java.io.File`) grails.doc.style - The location of a directory containing custom HTML templates for the guide (type `java.io.File`) grails.doc.images - The location of a directory containing image files for use in the style templates and within the documentation pages themselves (type `java.io.File`) One of the simplest ways to customise the look of the generated guide is to provide a value for `grails.doc.css` and then put a custom.css file in the corresponding directory. Grails will automatically include this CSS file in the guide. You can also place a custom-pdf.css file in that directory. This allows you to override the styles for the PDF version of the guide. #### Generating Documentation Add the plugin in your `build.gradle`:
    apply plugin: "org.grails.grails-doc"
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:
    gradle docs
This command will output an `docs/manual/index.html` which can be opened in a browser 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!
You can also link to internal images like so:
    !someFolder/my_diagram.png!
This will link to an image stored locally within your project. There is currently no default location for doc images, but you can specify one with the `grails.doc.images` setting in application.groovy like so:
    grails.doc.images = new File("src/docs/images")
In this example, you would put the my_diagram.png file in the directory 'src/docs/images/someFolder'. ##### 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:
    [Pivotal|http://www.pivotal.io/oss]
or
    "Pivotal":http://www.pivotal.io/oss
For links to other sections inside the user guide you can use the `guide:` prefix with the name of the section you want to link to:
    [Intro|guide:introduction]
The section name comes from the corresponding gdoc filename. The documentation engine will warn you if any links to sections in your guide break. To link to reference items you can use a special syntax:
    [renderPDF|controllers]
In this case the category of the reference item is on the right hand side of the | and the name of the reference item on the left. 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. To add additional APIs to the engine you can configure them in `grails-app/conf/application.groovy`. For example:
    grails.doc.api.org.hibernate=
                "http://docs.jboss.org/hibernate/stable/core/javadocs"
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}
| Quick Reference (hide)