Merge branch 'master' of github.com:grails/grails-doc

.travis.yml

@@ -0,0 +1,25 @@
+script: ./travis-build.sh
+sudo: false
+jdk:
+- openjdk7
+env:
+  global:
+  - GRADLE_OPTS="-server -Xmx1024M -Xms768M -XX:PermSize=256m -XX:MaxPermSize=512m"
+  - GIT_NAME="Graeme Rocher"
+  - GIT_EMAIL="[email protected]"
+  - secure: SdGzn2ItEkM0UGzByv/0yXLO7g9iJYmrSIgQ3a1yZXvOerQOLuOwwTZIJ4LUBJpJcQRhiAff1HidN/6fAGAd4mwgoQcX1kKdrRHIl0oG7V7DC9YRytPko/gasQ6aPoR3GBBpLqx8hIjGYbVKIrPWgMSRRA7DSvbzI5XlOgAX1Dg=
+  - secure: R9aL92lh09LniCTbiZuuikiWHXL4ik/DDAKe7NLanqpI126vs5Y9zd56JifgN8Mp7sEbwlaM4RzFXpgkdl57FZqdDzC04ljeqy9Z4CmGthUCF2o2exV98HFWxrL6J18OH5zVSBtZJN0ANcgdJ3/+vMuk2wyS61qhl36uiUM66tM=
+cache:
+  directories:
+  - $HOME/.gradle/wrapper
+  - $HOME/.gradle/caches
+deploy:
+  provider: releases
+  api_key:
+    secure: OXqyhH6/rK9rmiApnm+8smg/+rjdM3T28/4ZUzbdibYZNSagVAMniDgndZIwt198jDvAPxf9jadN1G3OD5BLkW0wUWvAfYAtxAwOe6dzgcsMavdTxoBJnjXBc4XqFXSDhWTO4cd4vQ5Wx6cyvbUY5xgyREpvEP7oRUgQ0RJo9q8=
+  file: build/distributions/grails-docs-${TRAVIS_TAG:1}.zip
+  skip_cleanup: true
+  on:
+    repo: grails/grails-doc
+    tags: true
+    all_branches: true

README.md

@@ -1,100 +1,10 @@
 Grails User/Reference Guide
 ===========================
 
-This is the project for generating the [Grails user & reference guide][Grails Documentation] that explains how to build applications with the [Grails][Grails] framework.
+This is the project for generating the [Grails user & reference guide][Grails Documentation] that explains how to build applications with the [Grails][Grails] framework. 
+
+For contributing to grails docs look at [Building/Contibuting to Grails Documentation][Building/Contibuting to Grails Documentation]
 
 [Grails Documentation]: http://grails.org/doc/latest
 [Grails]: http://grails.org
-
-Building the Guide
-------------------
-
-To build the documentation, simply type:
-
-    ./gradlew docs
-
-Be warned: this command can take a while to complete and you should probably increase your Gradle memory settings by giving the `GRADLE_OPTS` environment variable a value like
-
-    export GRADLE_OPTS="-Xmx512m -XX:MaxPermSize=384m"
-
-Fortunately, you can reduce the overall build time with a couple of useful options. The first allows you to specify the location of the Grails source to use:
-
-    ./gradlew -Dgrails.home=/home/user/projects/grails-core docs 
-
-The Grails source is required because the guide links to its API documentation and the build needs to ensure it's generated. If you don't specify a `grails.home` property, then the build will fetch the Grails source - a download of 10s of megabytes. It must then compile the Grails source which can take a while too.
-
-Additionally you can create a local.properties file with this variable set:
-
-    grails.home=/home/user/projects/grails-core
-
-or
-
-    grails.home=../grails-core
-
-The other useful option allows you to disable the generation of the API documentation, since you only need to do it once:
-
-    ./gradlew -Ddisable.groovydocs=true docs
-
-Again, this can save a significant amount of time and memory.
-
-The main English user guide is generated in the `build/docs` directory, with the `guide` sub-directory containing the user guide part and the `ref` folder containing the reference material. To view the user guide, simply open `build/docs/index.html`.
-
-If you want to enable building of translations, you can use:
-
-    ./gradlew -Dall.langs=true docs
-
-Contributing Documentation
---------------------------
-
-The publishing system for the user guide is the same as [the one for Grails projects][1]. You write your chapters and sections in the gdoc wiki format which is then converted to HTML for the final guide. Each chapter is a top-level gdoc file in the `src/<lang>/guide` directory. Sections and sub-sections then go into directories with the same name as the chapter gdoc but without the suffix.
-
-The structure of the user guide is defined in the `src/<lang>/guide/toc.yml` file, which is a [YAML][2] file. This file also defines the (language-specific) section titles. If you add or remove a gdoc file, you must update the TOC as well!
-
-The `src/<lang>/ref` directory contains the source for the reference sidebar. Each directory is the name of a category, which also appears in the docs. Hence the directories need different names for the different languages. Inside the directories go the gdoc files, whose names match the names of the methods, commands, properties or whatever that the files describe.
-
-Translations
-------------
-
-This project can host multiple translations of the user guide, with `src/en` being the main one. To add another one, simply create a new language directory under `src` and copy into it all the files under `src/en`. The build will take care of the rest.
-
-Once you have a copy of the original guide, you can use the `{hidden}` macro to wrap the English text that you have replaced, rather than remove it. This makes it easier to compare changes to the English guide against your translation. For example:
-
-    {hidden}
-    When you create a Grails application with the [create-app|commandLine] command,
-    Grails doesn't automatically create an Ant @build.xml@ file but you can generate
-    one with the [integrate-with|commandLine] command:
-    {hidden}
-
-    Quando crias uma aplicação Grails com o comando [create-app|commandLine], Grails
-    não cria automaticamente um ficheiro de construção Ant @build.xml@ mas podes gerar
-    um com o comando [integrate-with|commandLine]:
-
-Because the English text remains in your gdoc files, 'diff' will show differences on the English lines. You can then use the output of 'diff' to see which bits of your translation need updating. On top of that, the `{hidden}` macro ensures that the text inside it is not displayed in the browser, although you can display it by adding this URL as a bookmark: `javascript:toggleHidden();` (requires you to build the user guide with Grails 2.0 M2 or later).
-
-Even better, you can use the `left_to_do.groovy` script in the root of the project to see what still needs translating. You run it like so:
-
-    ./left_to_do.groovy es
-
-This will then print out a recursive diff of the given translation against the reference English user guide. Anything in {hidden} blocks that hasn't changed since being translated will _not_ appear in the diff output. In other words, all you will see is content that hasn't been translated yet and content that has changed since it was translated. Note that {code} blocks are ignored, so you _don't_ need to include them inside {hidden} macros.
-
-To provide translations for the headers, such as the user guide title and subtitle, just add language specific entries in the `resources/doc.properties` file like so:
-
-    es.title=El Grails Framework
-    es.subtitle=...
-
-For each language translation, properties beginning '<lang>.' will override the standard ones. In the above example, the user guide title will be El Grails Framework for the Spanish translation. Also, translators can be credited by adding a '<lang>.translators' property:
-
-    fr.translators=Stéphane Maldini
-
-This should be a comma-separated list of names (or the native language equivalent) and it will be displayed as a "Translated by" header in the user guide itself.
-
-You can build specific translations very easily using the `publishGuide_*` and `publishPdf_*` tasks. For example, to build both the French HTML and PDF user guides, simply execute
-
-    ./gradlew publishPdf_fr
-
-Each translation is generated in its own directory, so for example the French guide will end up in `build/docs/fr`. You can then view the translated guide by opening `build/docs/<lang>/index.html`.
-
-All translations are created as part of the [Hudson CI build for the grails-doc][2] project, so you can easily see what the current state is without having to build the docs yourself.
-
-[1]: http://grails.org/doc/2.0.0.M1/guide/conf.html#docengine
-[2]: http://hudson.grails.org/job/grails_docs_2.0.x/lastSuccessfulBuild/artifact/build/docs/
+[Building/Contibuting to Grails Documentation]: https://grails.github.io/grails-doc/latest/guide/contributing.html#patchesDoc

build.gradle

@@ -1,12 +1,12 @@
 apply plugin: "base"
 
-version = System.getProperty("grails.version") ?: "2.4.2"
+version = project.getProperty("grails.version")
 
 archivesBaseName = "grails-docs"
 
 ext.checkOutDir = "${buildDir.path}/checkout"
 ext.outputDir = "${buildDir.path}/docs"
-ext.githubBranch = "2.4.x"
+ext.githubBranch = "3.0.x"
 
 ext.explicitGrailsHome = System.getProperty("grails.home")
 ext.grailsHome = explicitGrailsHome ? file(explicitGrailsHome).absolutePath : "$checkOutDir/grails-src"
@@ -22,11 +22,15 @@ buildscript {
     }
 
     dependencies {
-        classpath "org.grails:grails-docs:2.4.2"
-        classpath 'org.codehaus.groovy:groovy-all:2.3.0'
+        classpath "org.grails:grails-docs:3.0.0"
+        classpath 'org.codehaus.groovy:groovy-all:2.4.0'
     }
 }
 
+task buildscriptDependencies(type: DependencyReportTask) {
+    configurations = [buildscript.configurations.classpath]
+}
+
 // use jsoup in PdfBuilder for cleaning input html
 System.setProperty('grails.docs.clean.html','true')
 // creates single.html.before.xml and single.html.after.xml files for debugging pdf input when enabled
@@ -38,7 +42,7 @@ task fetchGrailsSource << {
     println "Downloading Grails source code. If you already have a copy " +
             "of the Grails source code checked out you can avoid this download " +
             "by setting the grails.home system property to point to your local " +
-            "copy of the source. See README.txt for more information."
+            "copy of the source. See README.md for more information."
 
     def zipFile = "${checkOutDir}/grails-src.zip"
     ant.get src: "http://github.com/grails/grails-core/zipball/${githubBranch}", dest: zipFile, verbose: true
@@ -47,15 +51,17 @@ task fetchGrailsSource << {
         mapper type: "regexp", from: "(grails-grails-core-\\S*?/)(.*)", to: "grails-src/\\2"
     }
 
+    ant.chmod(file:"${checkOutDir}/grails-src/gradlew", perm:700)
+
     println "Grails source code has been downloaded to ${relativePath(grailsHome)}"
 }
 
 fetchGrailsSource.onlyIf { !explicitGrailsHome }
 
-task apiDocs(type: GradleBuild, dependsOn: 'fetchGrailsSource') {
-    tasks = ["groovydoc"]
-    buildFile = "${project.grailsHome}/build.gradle"
-    startParameter.excludedTaskNames = ['compileGroovy', 'compileUaaGroovy', 'compileJsp21Groovy', 'compileAstGroovy', 'jar']
+task apiDocs(type: Exec, dependsOn: 'fetchGrailsSource') {
+    commandLine = ["./gradlew", "groovydoc", '--info', '--stacktrace']
+    workingDir = "${checkOutDir}/grails-src"
+    environment "GRADLE_OPTS", "-Xmx2048m -Xms256m -XX:MaxPermSize=512m -XX:+CMSClassUnloadingEnabled -XX:+HeapDumpOnOutOfMemoryError"
 }
 
 apiDocs.onlyIf { !System.getProperty("disable.groovydocs") }
@@ -78,7 +84,7 @@ task publishGuide(type: grails.doc.gradle.PublishGuide, dependsOn: ['apiDocs', '
     // generated with a 'en' in the path, but the source is in 'en'
     // so that it's easy to track with git.
     sourceDir = new File(projectDir, "src/en")
-    propertiesFiles = [ new File(project.grailsHome, "build.properties") ]
+    propertiesFiles = [ new File(projectDir, "gradle.properties") ]
     macros = [ new grails.doc.macros.GspTagSourceMacro(searchDirs) ]
 }
 

gradle.properties

@@ -0,0 +1 @@
+grails.version=3.0.2

gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,6 @@
-#Wed May 07 15:07:35 EEST 2014
+#Thu Feb 19 15:21:28 CST 2015
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-1.12-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-2.3-bin.zip

quick-publish.sh

@@ -1 +1 @@
-./gradlew -Ddisable.groovydocs=true -Dgrails.home=../grails-master docs
+./gradlew -Ddisable.groovydocs=true -Dgrails.home=../dev docs 

resources/doc.properties

@@ -2,7 +2,6 @@ title=The Grails Framework
 subtitle=See the light - agile, industrial strength, rapid web application development made easy
 authors=Graeme Rocher, Peter Ledbrook, Marc Palmer, Jeff Brown, Luke Daley, Burt Beckwith, Lari Hotari
 copyright=Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.
-footer=Sponsored by <a href="http://www.gopivotal.com/oss">Pivotal</a>
 # aliases are used in links to bind to a more specific topic name such as [GSP|guide:gsp]
 alias.resources=6.2.5 Static Resources
 alias.ajax=6.7 Ajax
@@ -85,13 +84,14 @@ alias.XML=6.1.7 XML and JSON Responses
 
 # javadoc alias used to link to external javadocs in the form [HttpServletRequest|api:javax.servlet.http.HttpServletRequest]
 api.org.hibernate=http://docs.jboss.org/hibernate/core/3.6/javadocs
+api.org.springframework.boot=http://docs.spring.io/spring-boot/docs/current/api
 api.org.springframework=http://docs.spring.io/spring/docs/4.0.x/javadoc-api
 api.javax.servlet=http://download.oracle.com/javaee/1.4/api
 api.java.=http://docs.oracle.com/javase/6/docs/api
-api.groovy.=http://beta.groovy-lang.org/docs/groovy-2.3.0/html/api
-api.org.codehaus.groovy.grails=http://grails.org/doc/2.4.x/api
-api.grails.=http://grails.org/doc/2.4.x/api
-api.org.grails.=http://grails.org/doc/2.4.x/api
+api.groovy.=http://docs.groovy-lang.org/docs/latest/html/api
+api.org.codehaus.groovy.grails=http://grails.org/doc/3.0.x/api
+api.grails.=http://grails.org/doc/3.0.x/api
+api.org.grails.=http://grails.org/doc/3.0.x/api
 
 # Regular expression to parse out source code
 source.tag.regex=/\s*?def\s+?[a-zA-Z]+?\s*?=\s*?\{\s*?attrs\s*?,{0,1}\s*?body{0,1}\s*?->.+?/

src/en/guide/GORM/advancedGORMFeatures/ormdsl/caching.gdoc

@@ -1,13 +1,14 @@
 h4. Setting up caching
 
-"Hibernate":http://www.hibernate.org/ features a second-level cache with a customizable cache provider. This needs to be configured in the @grails-app/conf/DataSource.groovy@ file as follows:
+"Hibernate":http://www.hibernate.org/ features a second-level cache with a customizable cache provider. This needs to be configured in the @grails-app/conf/application.yml@ file as follows:
 
-{code:java}
-hibernate {
-    cache.use_second_level_cache=true
-    cache.use_query_cache=true
-    cache.provider_class='org.hibernate.cache.EhCacheProvider'
-}
+{code}
+hibernate:
+  cache:
+    use_second_level_cache: true
+    provider_class: net.sf.ehcache.hibernate.EhCacheProvider
+    region:
+       factory_class: org.hibernate.cache.ehcache.EhCacheRegionFactory
 {code}
 
 You can customize any of these settings, for example to use a distributed caching mechanism.
@@ -103,5 +104,5 @@ Below is a description of the different cache settings and their usages:
 
 * @read-only@ - If your application needs to read but never modify instances of a persistent class, a read-only cache may be used.
 * @read-write@ - If the application needs to update data, a read-write cache might be appropriate.
-* @nonstrict-read-write@ - If the application only occasionally needs to update data (ie. if it is very unlikely that two transactions would try to update the same item simultaneously) and strict transaction isolation is not required, a @nonstrict-read-write@ cache might be appropriate.
-* @transactional@ - The @transactional@ cache strategy provides support for fully transactional cache providers such as JBoss TreeCache. Such a cache may only be used in a JTA environment and you must specify @hibernate.transaction.manager_lookup_class@ in the @grails-app/conf/DataSource.groovy@ file's @hibernate@ config.
+* @nonstrict-read-write@ - If the application only occasionally needs to update data (i.e. if it is very unlikely that two transactions would try to update the same item simultaneously) and strict transaction isolation is not required, a @nonstrict-read-write@ cache might be appropriate.
+* @transactional@ - The @transactional@ cache strategy provides support for fully transactional cache providers such as JBoss TreeCache. Such a cache may only be used in a JTA environment and you must specify @hibernate.transaction.manager_lookup_class@ in the @grails-app/conf/application.groovy@ file's @hibernate@ config.

src/en/guide/GORM/advancedGORMFeatures/ormdsl/customNamingStrategy.gdoc

@@ -1,6 +1,6 @@
 By default Grails uses Hibernate's @ImprovedNamingStrategy@ to convert domain class Class and field names to SQL table and column names by converting from camel-cased Strings to ones that use underscores as word separators. You can customize these on a per-class basis in the @mapping@ closure but if there's a consistent pattern you can specify a different @NamingStrategy@ class to use.
 
-Configure the class name to be used in @grails-app/conf/DataSource.groovy@ in the @hibernate@ section, e.g.
+Configure the class name to be used in @grails-app/conf/application.groovy@ in the @hibernate@ section, e.g.
 
 {code:java}
 dataSource {

src/en/guide/GORM/advancedGORMFeatures/ormdsl/tableAndColumnNames.gdoc

@@ -33,7 +33,7 @@ Here @firstName@ is a dynamic method within the @mapping@ Closure that has a sin
 
 h4. Column type
 
-GORM supports configuration of Hibernate types with the DSL using the type attribute. This includes specifing user types that implement the Hibernate [org.hibernate.usertype.UserType|api:org.hibernate.usertype.UserType] interface, which allows complete customization of how a type is persisted. As an example if you had a @PostCodeType@ you could use it as follows:
+GORM supports configuration of Hibernate types with the DSL using the type attribute. This includes specifying user types that implement the Hibernate [org.hibernate.usertype.UserType|api:org.hibernate.usertype.UserType] interface, which allows complete customization of how a type is persisted. As an example if you had a @PostCodeType@ you could use it as follows:
 
 {code:java}
 class Address {

src/en/guide/GORM/domainClasses/gormAssociation/basicCollectionTypes.gdoc

@@ -15,7 +15,7 @@ class Person {
     static hasMany = [nicknames: String]
 
     static mapping = {
-       hasMany joinTable: [name: 'bunch_o_nicknames',
+       nicknames joinTable: [name: 'bunch_o_nicknames',
                            key: 'person_id',
                            column: 'nickname',
                            type: "text"]

src/en/guide/GORM/domainClasses/gormAssociation/manyToOneAndOneToOne.gdoc

@@ -64,7 +64,7 @@ class Nose {
 }
 {code}
 
-Note that using this property puts the foreign key on the inverse table to the previous example, so in this case the foreign key column is stored in the @nose@ table inside a column called @face_id@. Also, @hasOne@ only works with bidirectional relationships.
+Note that using this property puts the foreign key on the inverse table to the example A, so in this case the foreign key column is stored in the @nose@ table inside a column called @face_id@. Also, @hasOne@ only works with bidirectional relationships.
 
 Finally, it's a good idea to add a unique constraint on one side of the one-to-one relationship:
 

src/en/guide/GORM/domainClasses/sets,ListsAndMaps.gdoc

@@ -8,7 +8,7 @@ class Author {
 }
 {code}
 
-The books property that GORM injects is a @java.util.Set@. Sets guarantee uniquenes but not order, which may not be what you want. To have custom ordering you configure the Set as a @SortedSet@:
+The books property that GORM injects is a @java.util.Set@. Sets guarantee uniqueness but not order, which may not be what you want. To have custom ordering you configure the Set as a @SortedSet@:
 
 {code}
 class Author {

src/en/guide/GORM/querying/criteria.gdoc

@@ -256,7 +256,7 @@ def accountNumber = results.getLong('number')
 To quote the documentation of Hibernate ScrollableResults:
 
 {quote}
-A result iterator that allows moving around within the results by arbitrary increments. The Query / ScrollableResults pattern is very similar to the JDBC PreparedStatement/ ResultSet pattern and the semantics of methods of this interface are similar to the similarly named methods on ResultSet.
+A result iterator that allows moving around within the results by arbitrary increments. The Query / ScrollableResults pattern is very similar to the JDBC PreparedStatement / ResultSet pattern and the semantics of methods of this interface are similar to the similarly named methods on ResultSet.
 {quote}
 
 Contrary to JDBC, columns of results are numbered from zero.