////
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
////

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 https://txstyle.de/[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:

[source,groovy]
----
+ 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 http://www.yaml.org/[YAML] format and basically represents the structure of the user guide in tree form. For example, the above files could be represented as:

[source,yaml]
----
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:

[source,groovy]
----
+ 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`:

[source,groovy]
----
apply plugin: "org.apache.grails.gradle.grails-docs"
----

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:

[source,groovy]
----
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`
[source,groovy]
----
\`monospace\`
----

Italic: _italic_
[source,groovy]
----
\_italic\_
----

Bold: *bold*
[source,groovy]
----
*bold*
----

Image:
image::http://grails.org/images/new/grailslogo_topNav.png[]

[source,xml]
----
\!http://grails.org/images/new/grailslogo_topNav.png\!
----

You can also link to internal images like so:

[source,xml]
----
\!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:

[source,groovy]
----
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:

[source,groovy]
----
http://www.pivotal.io/oss[Pivotal]
----

or

[source,groovy]
----
http://www.pivotal.io/oss[Pivotal] ----

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:

[source,groovy]
----
<<introduction,Intro>>
----

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:

[source,groovy]
----
<<ref-controllers-renderPDF,renderPDF>>
----

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:

[source,groovy]
----
{javase}java.base/java/lang/String.html[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:

[source,groovy]
----
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:

[source,groovy]
----
h3.<space>Heading3
h4.<space>Heading4
----

Unordered lists are defined with the use of the * character:

[source,groovy]
----
* item 1
** subitem 1
** subitem 2
* item 2
----

Numbered lists can be defined with the # character:

[source,groovy]
----
# item 1
----

Tables can be created using the `table` macro:

[format="csv", options="header"]
|===

*Name*,*Number*
Albert,46
Wilma,1348
James,12
|===

[source,groovy]
----
\[format="csv", options="header"]
|===

*Name*,*Number*
Albert,46
Wilma,1348
James,12
\
|===
----


===== Code and Notes


You can define code blocks with the `code` macro:

[source,groovy]
----
class Book {
    String title
}
----

[source,groovy]
----
\{code\}
class Book {
    String title
}
\{code\}
----

The example above provides syntax highlighting for Java and Groovy code, but you can also highlight XML markup:

[source,xml]
----
<hello>world</hello>
----

[source,groovy]
----
\
<hello>world</hello>
\{code\}
----

There are also a couple of macros for displaying notes and warnings:

Note:
NOTE: This is a note!

[source,groovy]
----
\{note\}
This is a note!
\{note\}
----

Warning:

WARNING: This is a warning!

[source,groovy]
----
\{warning\}
This is a warning!
\{warning\}
----
