diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index dc7bc9f..b404a1b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -89,4 +89,3 @@ fix any minor problems than not have the contribution at all.
Ultimately, be aware that the maintainers don't have much time to dedicate to
processing pull requests, so the less work they have to do the more likely and
quickly they can merge those pull requests in.
-
diff --git a/README.md b/README.md
index 8030bbe..d9f8594 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,10 @@
+[](https://travis-ci.org/pledbrook/lazybones)
+
Lazybones Project Creation Tool
===============================
+
-
-So if you wanted to create a skeleton Ratpack project in a new 'my-rat-app'
-directory you would run
-
- lazybones create ratpack 1.2.0 my-rat-app
-
-The version is optional and if you leave it out, Lazybones will install the
-latest version of the template it can find.
-
-Named templates are all stored on Bintray. By default, Lazybones searches for
-templates in the pledbrook/lazybones-templates repository, but you can use
-other Bintray repositories by adding some configuration - set the Custom
-Repositories section under Configuration later in this document.
-
-You're not limited to only Bintray as you can install templates directly from
-a URL too:
-
- lazybones create http://dl.bintray.com/kyleboon/lazybones/java-basic-template-0.1.zip my-app
-
-Of course it can be pretty laborious copying and pasting URLs around, so Lazybones
-allows you to configure aliases for URLs that you use frequently. By adding the
-following configuration to your Lazybones settings file, `~/.lazybones/config.groovy`
-(see below for more details on this), you can install the template by name:
-
- templates {
- mappings {
- myTmpl = "http://dl.bintray.com/..."
- }
- }
-
-In other words, you could now run
-
- lazybones create myTmpl my-app
-
-Note that when using the URL option, there is no need to specify a version. You
-should also be aware that mappings take precedence, i.e. if a mapping has the
-same name as an existing template, the mapping is used. This essentially creates
-a simple override mechanism.
-
-There is just one more thing to say about the `create` command: by default it
-creates the specified directory and puts the initial project in there. If you
-want to unpack a template in the current directory instead, for example if you
-have already created the project directory, then just pass '.' as the directory:
-
- lazybones create ratpack .
-
-Once you have created a new project from a template, you may notice that the
-project directory contains a .lazybones sub directory. You may delete this, but
-then you won't be able to use the `generate` command (see next section) if the
-project template has support for it.
-
-Many project templates request information from you, such as a project name, a
-group ID, a default package, etc. If this is the umpteenth time you have created
-a project from a given template, then answering the questions can become tedious.
-There is also the problem of scripting and automation when you want to create
-a project without user intervention. The solution to both these issues is to
-pass the values on the command line:
-
- lazybones create ratpack 1.2.0 ratapp -Pgroup=org.example -Ppackage=org.example.myapp
-
-The `-P` option allows you to pass property values into the project templates
-without user intervention. The key is to know what the property names are, and
-that comes down to the project template. At the moment, the best way to find out
-what those properties are is to look at the post-install script itself.
-
-The last option to mention is `--with-git` which will automatically create a
-new git repository in the project directory. The only requirement is that you
-have the `git` command on your path.
-
-### Sub-templates
-
-As of Lazybones version 0.7, project templates can incorporate subtemplates.
-Imagine that you have just created a new web application project from a template
-and that template documents that you can create new controllers using a sub-
-template named `controller`. To use it, just `cd` into the project directory
-and run
-
- lazybones generate controller
-
-This will probably ask you for the name of the controller and its package before
-generating the corresponding controller file in your project. You can reuse the
-command to create as many controllers as you need.
-
-As with the `create` command, you can also pass in property values on the command
-line if the subtemplate is parameterised:
-
- lazybones generate controller -Ppackage=org.example.myapp -Pclass=Book
-
-The last option available to you as a user is template qualifiers. These only
-work if the subtemplate supports them, but they allow you to pass additional
-information in a concise way:
-
- lazybones generate artifact::controller
-
-In this case, the template name is `artifact`, but we have qualified it with
-an extra `controller`. You can pass in as many qualifiers as you want, you just
-separate them with `::`.
-
-Note that you do not specify a version with the `generate` command. This is
-because the subtemplates are embedded directly in the project template, and
-so there can only be one version available to you.
-
-### Finding out what templates are available
-
-To see what templates you can install, run
-
- lazybones list
-
-This will list all aliases and remote templates. If you want to see what
-templates you have cached locally, run
-
- lazybones list --cached
-
-In fact, `--cached` is implied if Lazybones can't connect to the internet.
-
-You can also find out more about a template through the `info` command:
-
- lazybones info
-
-This will print a description of the template and what versions are available
-for it. If you're offline, this will simply display an error message.
-
-## Configuration
-
-Lazybones will run out of the box without any extra configuration, but the tool
-does allow you to override the default behaviour via a fixed set of configuration
-options. These options can be provided in a number of ways following a set order
-of precedence:
-
-1. System properties of the form `lazybones.*`, which can be passed into the app
-via either `JAVA_OPTS` or `LAZYBONES_OPTS` environment variables. For example:
-
- env JAVA_OPTS="-Dlazybones.config.file=/path/to/my-custom-default-config.groovy" lazybones ...
-
- Highest precedence, i.e. it overrides all other sources of setting data.
-
-2. User configuration file in `$USER_HOME/.lazybones/config.groovy`. This is parsed
-using Groovy's `ConfigSlurper`, so if you're familiar with that syntax you'll be
-right at home. Otherwise, just see the examples below.
-
-3. (Since 0.8) A JSON configuration file in `$USER_HOME/.lazybones/managed-config.groovy`
-that is used by the `config` commands. You can edit it this as well.
-
-4. A Groovy-based default configuration file that is provided by the application
-itself, but you can specify an alternative file via the `lazybones.config.file`
-system property.
-
-Lazybones also provides a convenient mechanism for setting and removing options
-via the command line: the `config` command.
-
-### Command line configuration
-
-The `config` command provides several sub-commands that allow you to interact with
-the persisted Lazybones configuration; specifically, the JSON config file. You
-run a sub-command via
-
- lazybones config
-
-where `` is one of:
-
-* `set [ ...]`
-
- Allows you to change the value of a configuration setting. Multiple values are
- treated as a single array/list value. The new value replaces any existing one.
-
-* `add `
-
- Appends an extra value to an existing array/list setting. Reports an error if
- the setting doesn't accept multiple values. If the setting doesn't already have
- a value, this command will initialise it with an array containing the given
- value.
-
-* `clear `
-
- Removes a setting from the configuration, effectively reverting it to whatever
- the internal default is.
-
-* `show [--all] `
-
- Shows the current value of a setting. You can use the `--all` argument (without
- a setting name) to display all the current settings and their values.
-
-* `list`
-
- Displays all the configuration settings supported by Lazybones.
-
-So what configuration settings are you likely to customise?
-
-### Custom repositories
-
-Lazybones will by default download the templates from a specific Bintray
-repository. If you want to host template packages in a different repository
-you can add it to Lazybone's search path via the `bintrayRepositories`
-setting:
-
- bintrayRepositories = [
- "kyleboon/lazybones",
- "pledbrook/lazybones-templates"
- ]
-
-If a template exists in more than one repository, it will be downloaded from the
-first repository in the list that it appears in.
-
-### Package aliases
-
-If you regularly use a template at a specific URL rather than from Bintray, then
-you will want to alias that URL to a name. That's where template mappings (or
-aliases) come in. The aliases are defined as normal settings of the form
-
- templates.mappings. =
-
-In a Groovy configuration file, you can define multiple aliases in a block:
-
- templates {
- mappings {
- test = "http://dl.dropboxusercontent.com/u/29802534/custom-ratpack.zip"
- after = "file:///var/tmp/afterburnerfx-2.0.0.zip"
- }
- }
-
-Alternatively, add them from the command line like this:
-
- lazybones config set templates.mappings.after file:///var/tmp/afterburnerfx-2.0.0.zip
-
-The aliases will always be available to you until you remove them from the persisted
-configuration.
-
-### Setting a proxy (and other system properties) (Since 0.8.1)
-
-Many people have to work behind a proxy, but Lazybones didn't make it easy to
-configure one. In fact the only way to do it was to add the relevant system
-properties to a `JAVA_OPTS` environment variable. From 0.8.1, you now have another
-option.
-
-Lazybones has stolen the idea of having a special form of configuration option for
-system properties from Gradle. So if you define a property with a `systemProp.`
-prefix, it will be added as a system property internally. So to configure an HTTP
-proxy, you only need to add the following to your Lazybones configuration:
-
- systemProp {
- http {
- proxyHost = "localhost"
- proxyPort = 8181
- }
- https {
- proxyHost = "localhost"
- proxyPort = 8181
- }
- }
-
-To avoid potential configuration issues, use the same proxy settings for HTTP and
-HTTPS if possible.
-
-If your proxy requires authentication, you will need to add a couple of extra
-properties:
-
- systemProp {
- http {
- proxyUser = "johndoe"
- proxyPassword = "mypassword"
- }
- }
-
-As with the host and port, there are `https` variants of the username and passwordi
-as well.
-
-### General options
-
-These are miscellaneous options that can be overridden on the command line:
-
- // <-- This starts a line comment
- // Set logging level - overridden by command line args
- options.logLevel = "SEVERE"
-
-The logging level can either be overridden using the same `logLevel` setting:
-
- lazybones --logLevel SEVERE info ratpack
-
-or via `--verbose`, `--quiet`, and `--info` options:
-
- lazybones --verbose info ratpack
-
-The logging level can be one of:
-
-* OFF
-* SEVERE
-* WARNING
-* INFO
-* FINE
-* FINEST
-* ALL
-
-## Building it
-
-This project is split into two parts:
-
-1. The lazybones command line tool; and
-2. The project templates.
-
-### The command line tool
-
-The command line tool is created via Gradle's application plugin. The main
-class is `uk.co.cacoethes.lazybones.LazyBonesMain`, which currently implements
-all the sub-commands (create, list, etc.) as concrete methods.
-
-The main class plus everything else under src/main is packaged into a lazybones
-JAR that is included in the distribution zip. The application Gradle plugin
-generates a `lazybones` script that then runs the main class with all required
-dependencies on the classpath.
-
-To build the distribution, simply run
-
- ./gradlew distZip
-
-### The project templates
-
-The project templates are simply directory structures with whatever files in
-them that you want. Ultimately, the template project directories will be zipped
-up and stored on [Bintray](https://bintray.com/repo/browse/pledbrook/lazybones-templates).
-From there, lazybones downloads the zips on demand and caches them in a local
-user directory (currently ~/.lazybones/templates).
-
-If you want empty directories to form part of the project template, then simply
-add an empty .retain file to each one. When the template archive is created,
-any .retain files are filtered out (but the containing directories are included).
-
-To package up a template, simply run
-
- ./gradlew packageTemplate
-
-The name of the project template comes from the containing directory, which is
-assumed to be lowercase hyphenated. The template name is the equivalent camel
-case form. So the template directory structure in src/templates/my-template
-results in a template called 'MyTemplate', which can be packaged with
-
- ./gradlew packageTemplateMyTemplate
-
-The project template archive will be created in the build directory with the
-name '-template-.zip'. See the small section below on
-how the template version is derived.
-
-You can also package all the templates in one fell swoop:
-
- ./gradlew packageAllTemplates
-
-Once a template is packaged up, you can publish it to a generic (non-Maven)
-Bintray repository by running
-
- ./gradlew publishTemplate
-
-This will initially fail, because the build does not know where to publish to.
-That's quickly fixed by adding a gradle.properties file in the root of this
-project that contains at least these properties:
-
- repo.username=your_bintray_username
- repo.apiKey=your_bintray_apikey
-
-You can then publish new versions of templates whenever you want. Note that you
-cannot _republish_ with this mechanism, so remember to increment the version if
-you need to.
-
-Finally, you can publish the whole shebang (unusual) with
-
- ./gradlew publishAllTemplates
-
-If you don't want to publish your template you can install it locally using the
-installTemplate rule.
-
- ./gradlew installTemplate
-
-This will install the template to ~/.lazybones/templates so that you can use it without
-moving it to bintray first.
-
-And that's it for the project templates.
-
-#### Template versions
-
-You define the version of a template by putting a VERSION file in the root
-directory of the template that contains just the version number. For example,
-you specify a version of 1.2.8 for the my-template template by adding the file
-src/templates/my-template/VERSION with the contents
-
- 1.2.8
+Lazybones documentation
+-----------------------
-That's it! The VERSION file will automatically be excluded from the project
-template archive.
+You can find Lazybones documentation at
+https://pledbrook.github.io/lazybones/
-Contributing templates
-----------------------
+Contribution guidelines
+-----------------------
-Read the [Template Developers Guide](https://github.com/pledbrook/lazybones/wiki/Template-developers-guide)
-for information on how to create and publish Lazybones templates.
+There's a special chapter in the documentation on how to contribute to
+Lazybones. You can find it at
+https://pledbrook.github.io/lazybones/#_contribution_guidelines
diff --git a/lazybones-docs/docs.gradle b/lazybones-docs/docs.gradle
new file mode 100644
index 0000000..2e9e14b
--- /dev/null
+++ b/lazybones-docs/docs.gradle
@@ -0,0 +1,30 @@
+buildscript {
+ repositories {
+ jcenter()
+ }
+
+ dependencies {
+ classpath 'org.asciidoctor:asciidoctor-gradle-plugin:1.5.2'
+ classpath 'org.ajoberstar:gradle-git:1.4.2'
+ }
+}
+
+apply plugin: 'org.asciidoctor.convert'
+apply plugin: 'org.ajoberstar.github-pages'
+
+asciidoctor {
+ attributes 'source-highlighter': 'prettify',
+ toc : 'left',
+ icons : 'font',
+ toclevels : 3,
+ 'pdf-style' : 'default'
+}
+
+githubPages {
+ repoUri = 'https://github.com/pledbrook/lazybones.git'
+ deleteExistingFiles = true
+
+ pages {
+ from file('build/asciidoc/html5/')
+ }
+}
diff --git a/lazybones-docs/src/docs/asciidoc/build.adoc b/lazybones-docs/src/docs/asciidoc/build.adoc
new file mode 100644
index 0000000..e85c3f9
--- /dev/null
+++ b/lazybones-docs/src/docs/asciidoc/build.adoc
@@ -0,0 +1,125 @@
+== Build
+
+his project is split into two parts:
+
+* The lazybones command line tool; and
+* The project templates.
+
+=== Command line tool
+
+The command line tool is created via Gradle's application plugin. The
+main class is `uk.co.cacoethes.lazybones.LazyBonesMain`, which currently
+implements all the sub-commands (create, list, etc.) as concrete
+methods.
+
+The main class plus everything else under src/main is packaged into a
+`lazybones` JAR that is included in the distribution zip. The
+application Gradle plugin generates a lazybones script that then runs
+the main class with all required dependencies on the classpath.
+
+To build the distribution, simply run
+
+[source,shell]
+----
+./gradlew distZip
+----
+
+=== Project templates
+
+The project templates are simply directory structures with whatever
+files in them that you want. Ultimately, the template project
+directories will be zipped up and stored on
+https://bintray.com/repo/browse/pledbrook/lazybones-templates[Bintray]. From
+there, lazybones downloads the zips on demand and caches them in a
+local user directory (currently ~/.lazybones/templates).
+
+If you want empty directories to form part of the project template,
+then simply add an empty .retain file to each one. When the template
+archive is created, any .retain files are filtered out (but the
+containing directories are included).
+
+To package up a template, simply run
+
+[source,shell]
+----
+./gradlew packageTemplate
+----
+
+The name of the project template comes from the containing directory,
+which is assumed to be lowercase hyphenated. The template name is the
+equivalent camel case form. So the template directory structure in
+src/templates/my-template results in a template called 'MyTemplate',
+which can be packaged with
+
+[source,shell]
+----
+./gradlew packageTemplateMyTemplate
+----
+
+The project template archive will be created in the build directory
+with the name '-template-.zip'. See the small section below on how the
+template version is derived.
+
+You can also package all the templates in one fell swoop:
+
+[source,shell]
+----
+./gradlew packageAllTemplates
+----
+
+Once a template is packaged up, you can publish it to a generic (non-Maven) Bintray repository by running
+
+[source,shell]
+----
+./gradlew publishTemplate
+----
+
+This will initially fail, because the build does not know where to
+publish to. That's quickly fixed by adding a gradle.properties file in
+the root of this project that contains at least these properties:
+
+[source,shell]
+----
+repo.username=your_bintray_username
+repo.apiKey=your_bintray_apikey
+----
+
+You can then publish new versions of templates whenever you want. Note
+that you cannot republish with this mechanism, so remember to
+increment the version if you need to.
+
+Finally, you can publish the whole shebang (unusual) with
+
+[source,shell]
+----
+./gradlew publishAllTemplates
+----
+
+If you don't want to publish your template you can install it locally
+using the installTemplate rule.
+
+[source,shell]
+----
+ ./gradlew installTemplate
+----
+
+This will install the template to ~/.lazybones/templates so that you
+can use it without moving it to bintray first.
+
+And that's it for the project templates.
+
+=== Template versions
+
+You define the version of a template by putting a VERSION file in the
+root directory of the template that contains just the version
+number. For example, you specify a version of 1.2.8 for the
+my-template template by adding the file
+src/templates/my-template/VERSION with the contents
+
+[source,shell]
+----
+1.2.8
+----
+
+That's it! The VERSION file will automatically be excluded from the
+project template archive.
\ No newline at end of file
diff --git a/lazybones-docs/src/docs/asciidoc/configuration.adoc b/lazybones-docs/src/docs/asciidoc/configuration.adoc
new file mode 100644
index 0000000..04ccfd0
--- /dev/null
+++ b/lazybones-docs/src/docs/asciidoc/configuration.adoc
@@ -0,0 +1,214 @@
+== Configuration
+
+Lazybones will run out of the box without any extra configuration, but
+the tool does allow you to override the default behaviour via a fixed
+set of configuration options. These options can be provided in a
+number of ways following a set order of precedence:
+
+System properties of the form `lazybones.*`, which can be passed into
+the app via either `JAVA_OPTS` or `LAZYBONES_OPTS` environment
+variables. For example:
+
+[source,shell]
+----
+env JAVA_OPTS="-Dlazybones.config.file=/path/to/my-custom-default-config.groovy" lazybones ...
+----
+
+Highest precedence, i.e. it overrides all other sources of setting
+data.
+
+User configuration file in `$USER_HOME/.lazybones/config.groovy`. This
+is parsed using Groovy's ConfigSlurper, so if you're familiar with
+that syntax you'll be right at home. Otherwise, just see the examples
+below.
+
+(Since 0.8) A JSON configuration file in
+`$USER_HOME/.lazybones/managed-config.groovy` that is used by the
+config commands. You can edit it this as well.
+
+A Groovy-based default configuration file that is provided by the
+application itself, but you can specify an alternative file via the
+`lazybones.config.file` system property.
+
+Lazybones also provides a convenient mechanism for setting and
+removing options via the command line: the config command.
+
+=== Command line
+
+The config command provides several sub-commands that allow you to
+interact with the persisted Lazybones configuration; specifically, the
+JSON config file. You run a sub-command via
+
+[source,shell]
+----
+lazybones config
+----
+
+where `` is one of:
+
+* `set [ ...]`
+
+Allows you to change the value of a configuration setting. Multiple
+values are treated as a single array/list value. The new value
+replaces any existing one.
+
+* `add `
+
+Appends an extra value to an existing array/list setting. Reports an
+error if the setting doesn't accept multiple values. If the setting
+doesn't already have a value, this command will initialise it with an
+array containing the given value.
+
+* `clear `
+
+Removes a setting from the configuration, effectively reverting it to
+whatever the internal default is.
+
+* `show [--all] `
+
+Shows the current value of a setting. You can use the `--all` argument
+(without a setting name) to display all the current settings and their
+values.
+
+* `list`
+
+Displays all the configuration settings supported by Lazybones.
+
+So what configuration settings are you likely to customise?
+
+=== Custom Repositories
+
+Lazybones will by default download the templates from a specific
+Bintray repository. If you want to host template packages in a
+different repository you can add it to Lazybone's search path via the
+`bintrayRepositories` setting:
+
+[source,groovy]
+----
+bintrayRepositories = [
+ "kyleboon/lazybones",
+ "pledbrook/lazybones-templates"
+]
+----
+
+If a template exists in more than one repository, it will be
+downloaded from the first repository in the list that it appears in.
+
+=== Package aliases
+
+If you regularly use a template at a specific URL rather than from
+Bintray, then you will want to alias that URL to a name. That's where
+template mappings (or aliases) come in. The aliases are defined as
+normal settings of the form
+
+[source,groovy]
+----
+templates.mappings. =
+----
+
+In a Groovy configuration file, you can define multiple aliases in a block:
+
+[source,groovy]
+----
+templates {
+ mappings {
+ test = "http://dl.dropboxusercontent.com/u/29802534/custom-ratpack.zip"
+ after = "file:///var/tmp/afterburnerfx-2.0.0.zip"
+ }
+}
+----
+
+Alternatively, add them from the command line like this:
+
+[source,shell]
+----
+lazybones config set templates.mappings.after file:///var/tmp/afterburnerfx-2.0.0.zip
+----
+
+The aliases will always be available to you until you remove them from
+the persisted configuration.
+
+=== System properties
+
+**(Since 0.8.1)**
+
+Many people have to work behind a proxy, but Lazybones didn't make it
+easy to configure one. In fact the only way to do it was to add the
+relevant system properties to a `JAVA_OPTS` environment variable. From
+0.8.1, you now have another option.
+
+Lazybones has stolen the idea of having a special form of
+configuration option for system properties from Gradle. So if you
+define a property with a `systemProp`. prefix, it will be added as a
+system property internally. So to configure an HTTP proxy, you only
+need to add the following to your Lazybones configuration:
+
+[source,groovy]
+----
+systemProp {
+ http {
+ proxyHost = "localhost"
+ proxyPort = 8181
+ }
+ https {
+ proxyHost = "localhost"
+ proxyPort = 8181
+ }
+}
+----
+
+To avoid potential configuration issues, use the same proxy settings
+for HTTP and HTTPS if possible.
+
+If your proxy requires authentication, you will need to add a couple
+of extra properties:
+
+[source,groovy]
+----
+systemProp {
+ http {
+ proxyUser = "johndoe"
+ proxyPassword = "mypassword"
+ }
+}
+----
+
+As with the host and port, there are `https` variants of the username
+and passwordi as well.
+
+=== General options
+
+These are miscellaneous options that can be overridden on the command
+line:
+
+[source,groovy]
+----
+// <-- This starts a line comment
+// Set logging level - overridden by command line args
+options.logLevel = "SEVERE"
+----
+
+The logging level can either be overridden using the same logLevel
+setting:
+
+[source,shell]
+----
+lazybones --logLevel SEVERE info ratpack
+----
+
+or via `--verbose`, `--quiet`, and `--info` options:
+
+[source,shell]
+----
+lazybones --verbose info ratpack
+----
+
+The logging level can be one of:
+
+* OFF
+* SEVERE
+* WARNING
+* INFO
+* FINE
+* FINEST
+* ALL
diff --git a/lazybones-docs/src/docs/asciidoc/contributing.adoc b/lazybones-docs/src/docs/asciidoc/contributing.adoc
new file mode 100644
index 0000000..99fdcb0
--- /dev/null
+++ b/lazybones-docs/src/docs/asciidoc/contributing.adoc
@@ -0,0 +1,100 @@
+== Contribution guidelines
+
+We love to see contributions to the project and have tried to make it
+easy to do so, for example by keeping its scope small and the code
+equally so. If you wish to contribute code, then please keep to the
+following guidelines to ensure consistency within the codebase and
+that we have happy users.
+
+=== Philosophy
+
+Our approach to the project is to keep it small and narrowly
+focused. Expect new features to be discussed in-depth before being
+accepted (or rejected). This is not a framework, but a simple,
+easy-to-use tool for creating template projects. It offers useful
+utility functions to template authors, but nothing more.
+
+=== Documentation
+
+If you contribute anything that changes the behaviour of the
+application, document it in the README! This includes new features,
+additional variants of behaviour and breaking changes.
+
+Make a note of breaking changes in the pull request because they will
+need to go into the release notes.
+
+=== Testing
+
+This project uses
+http://spockframework.github.io/spock/docs/1.0/index.html[Spock] for
+its tests. Although any tests are better than none, Spock tests will
+be looked on more favourably than other types (such as JUnit). Plus
+you'll find writing the tests so much nicer!
+
+Unit tests are a nice to have, but it's the integration tests that are
+critical. These are run via
+
+[source,shell]
+----
+./gradlew integTest
+----
+
+and launch the lazybones executable as a separate process. The output
+is captured so that you can verify the content. The tests reside in
+the `src/integTest` directory and extend `AbstractFunctionalSpec`.
+
+They use https://github.com/betamaxteam/betamax[Betamax] to intercept
+and replay web requests (such as to the Bintray REST API and download
+URLs).
+
+=== Commit messages
+
+It may seem anal to request a particular format for commit messages,
+but these are a historical record of what's happening in the code base
+and consistency makes investigating that history much easier.
+
+Please follow the advice of the
+https://github.com/phonegap/phonegap/wiki/Git-Commit-Message-Format[Phonegap
+guys] when crafting commit messages. The advice basically comes down
+to:
+
+* First line should be maximum 50 characters long
+* It should summarise the change and use imperative present tense
+* The rest of the commit message should come after a blank line
+* We encourage you to use Markdown syntax in the rest of the commit
+ message
+* Preferably keep to an 80 character limit on lines in the rest of the
+ message.
+
+If a commit is related to a particular issue, put the issue number
+after a hash (#) somewhere in the detail. You can put the issue number
+in the first line summary, but only if you can also fit in a useful
+summary of what was changed in the commit.
+
+Here's an example git message:
+
+[quote]
+----
+Make create's version argument optional.
+
+Implements issue #3. If the user doesn't provide an explicit version, lazybones retrieves the latest version from Bintray. Integration tests added for the create `command` as well.
+----
+
+=== Formatting
+
+The rules are simple: use the same formatting as the rest of the
+code. The following is a list of the styles we are particularly
+particular about:
+
+* 4 space indent, no tabs
+* a space between if/elseif/catch/etc. keywords and the parenthesis
+* elseif/else/catch on their own lines
+
+If in doubt, submit the change and mention in the pull request that
+you're not sure about a particular style you used. We'd rather have
+the contribution and fix any minor problems than not have the
+contribution at all.
+
+Ultimately, be aware that the maintainers don't have much time to
+dedicate to processing pull requests, so the less work they have to do
+the more likely and quickly they can merge those pull requests in.
diff --git a/lazybones-docs/src/docs/asciidoc/create_projects.adoc b/lazybones-docs/src/docs/asciidoc/create_projects.adoc
new file mode 100644
index 0000000..b51175a
--- /dev/null
+++ b/lazybones-docs/src/docs/asciidoc/create_projects.adoc
@@ -0,0 +1,99 @@
+== Creating projects
+
+To create a new project, run
+
+[source,shell]
+----
+lazybones create
+----
+
+So if you wanted to create a skeleton Ratpack project in a new
+'my-rat-app' directory you would run
+
+[source,shell]
+----
+lazybones create ratpack 1.2.0 my-rat-app
+----
+
+The version is optional and if you leave it out, Lazybones will
+install the latest version of the template it can find.
+
+Named templates are all stored on Bintray. By default, Lazybones
+searches for templates in the pledbrook/lazybones-templates
+repository, but you can use other Bintray repositories by adding some
+configuration - set the Custom Repositories section under
+Configuration later in this document.
+
+You're not limited to only Bintray as you can install templates
+directly from a URL too:
+
+[source,shell]
+----
+lazybones create http://dl.bintray.com/kyleboon/lazybones/java-basic-template-0.1.zip my-app
+----
+
+Of course it can be pretty laborious copying and pasting URLs around,
+so Lazybones allows you to configure aliases for URLs that you use
+frequently. By adding the following configuration to your Lazybones
+settings file, `~/.lazybones/config.groovy` (see below for more details
+on this), you can install the template by name:
+
+[source,groovy]
+----
+templates {
+ mappings {
+ myTmpl = "http://dl.bintray.com/..."
+ }
+}
+----
+
+In other words, you could now run
+
+[source,shell]
+----
+lazybones create myTmpl my-app
+----
+
+Note that when using the URL option, there is no need to specify a
+version. You should also be aware that mappings take precedence,
+i.e. if a mapping has the same name as an existing template, the
+mapping is used. This essentially creates a simple override mechanism.
+
+There is just one more thing to say about the `create` command: by
+default it creates the specified directory and puts the initial
+project in there. If you want to unpack a template in the current
+directory instead, for example if you have already created the project
+directory, then just pass '.' as the directory:
+
+[source,groovy]
+----
+lazybones create ratpack .
+----
+
+Once you have created a new project from a template, you may notice
+that the project directory contains a .lazybones sub directory. You
+may delete this, but then you won't be able to use the `generate`
+command (see next section) if the project template has support for it.
+
+Many project templates request information from you, such as a project
+name, a group ID, a default package, etc. If this is the umpteenth
+time you have created a project from a given template, then answering
+the questions can become tedious. There is also the problem of
+scripting and automation when you want to create a project without
+user intervention. The solution to both these issues is to pass the
+values on the command line:
+
+[source,shell]
+----
+lazybones create ratpack 1.2.0 ratapp -Pgroup=org.example -Ppackage=org.example.myapp
+----
+
+The `-P` option allows you to pass property values into the project
+templates without user intervention. The key is to know what the
+property names are, and that comes down to the project template. At
+the moment, the best way to find out what those properties are is to
+look at the post-install script itself.
+
+The last option to mention is `--with-git` which will automatically
+create a new git repository in the project directory. The only
+requirement is that you have the git command on your path.
\ No newline at end of file
diff --git a/lazybones-docs/src/docs/asciidoc/credits.adoc b/lazybones-docs/src/docs/asciidoc/credits.adoc
new file mode 100644
index 0000000..b6b00a6
--- /dev/null
+++ b/lazybones-docs/src/docs/asciidoc/credits.adoc
@@ -0,0 +1,15 @@
+== Credits
+
+=== Developers
+
+* https://github.com/pledbrook[Peter Ledbrook]
+* https://github.com/kyleboon[Kyle Boon]
+* https://github.com/tbarker9[Tommy Barker]
+
+=== Contributors
+
+* https://github.com/alkemist[Luke Daley]
+* https://github.com/tomaslin[Tomas Lin]
+* https://github.com/rhart[Russell Hart]
+* https://github.com/dsyer[Dave Syer]
+* https://github.com/andyjduncan[Andy Duncan]
\ No newline at end of file
diff --git a/lazybones-docs/src/docs/asciidoc/images/lazybones-logo.svg b/lazybones-docs/src/docs/asciidoc/images/lazybones-logo.svg
new file mode 100644
index 0000000..5030f8e
--- /dev/null
+++ b/lazybones-docs/src/docs/asciidoc/images/lazybones-logo.svg
@@ -0,0 +1,10 @@
+
+
+
+
+
+
diff --git a/lazybones-docs/src/docs/asciidoc/index.adoc b/lazybones-docs/src/docs/asciidoc/index.adoc
new file mode 100644
index 0000000..f421777
--- /dev/null
+++ b/lazybones-docs/src/docs/asciidoc/index.adoc
@@ -0,0 +1,27 @@
+= Lazybones
+:numbered:
+:imagesDir: ./images/
+:baseDir: ../../
+:stem:
+
+image::lazybones-logo.svg[width=300, align=center]
+
+include::intro.adoc[]
+
+include::install.adoc[]
+
+include::create_projects.adoc[]
+
+include::subtemplates.adoc[]
+
+include::templates_search.adoc[]
+
+include::configuration.adoc[]
+
+include::build.adoc[]
+
+include::templates_development.adoc[]
+
+include::contributing.adoc[]
+
+include::credits.adoc[]
\ No newline at end of file
diff --git a/lazybones-docs/src/docs/asciidoc/install.adoc b/lazybones-docs/src/docs/asciidoc/install.adoc
new file mode 100644
index 0000000..6ddd042
--- /dev/null
+++ b/lazybones-docs/src/docs/asciidoc/install.adoc
@@ -0,0 +1,12 @@
+== Install it
+
+Grab lazybones from sdkman (formerly gvm):
+
+[source,shell]
+----
+sdk install lazybones
+----
+
+or alternatively, grab the distribution from
+Bintray, unpack it to a local directory, and then add its 'bin'
+directory to your PATH environment variable.
\ No newline at end of file
diff --git a/lazybones-docs/src/docs/asciidoc/intro.adoc b/lazybones-docs/src/docs/asciidoc/intro.adoc
new file mode 100644
index 0000000..e1f3fd5
--- /dev/null
+++ b/lazybones-docs/src/docs/asciidoc/intro.adoc
@@ -0,0 +1,23 @@
+== Intro
+
+Lazybones was born out of frustration that Ratpack does not and will
+not have a command line tool that will bootstrap a project. It's a
+good decision for Ratpack, but I'm lazy and want tools to do the
+boring stuff for me.
+
+The tool is very simple: it allows you to create a new project
+structure for any framework or library for which the tool has a
+template. You can even contribute templates by sending pull requests
+to this GitHub project or publishing the packages to the relevant
+Bintray repository (more info available below).
+
+The concept of Lazybones is very similar to Maven archetypes, and what
+Yeoman does for web applications. Lazybones also includes a
+subtemplates feature that resembles the behaviour of Yeoman's
+sub-generators, allowing you to generate optional extras (controllers,
+scaffolding etc.) inside a project.
+
+== License
+
+The *Lazybones* project is open sourced under the
+http://www.apache.org/licenses/LICENSE-2.0.html[Apache 2 License].
diff --git a/lazybones-docs/src/docs/asciidoc/subtemplates.adoc b/lazybones-docs/src/docs/asciidoc/subtemplates.adoc
new file mode 100644
index 0000000..d0a6728
--- /dev/null
+++ b/lazybones-docs/src/docs/asciidoc/subtemplates.adoc
@@ -0,0 +1,43 @@
+== Sub-templates
+
+As of Lazybones version 0.7, project templates can incorporate
+subtemplates. Imagine that you have just created a new web application
+project from a template and that template documents that you can
+create new controllers using a sub- template named `controller`. To
+use it, just `cd` into the project directory and run
+
+[source,shell]
+----
+lazybones generate controller
+----
+
+This will probably ask you for the name of the controller and its
+package before generating the corresponding controller file in your
+project. You can reuse the command to create as many controllers as
+you need.
+
+As with the `create` command, you can also pass in property values on
+the command line if the subtemplate is parameterised:
+
+[source,shell]
+----
+lazybones generate controller -Ppackage=org.example.myapp -Pclass=Book
+----
+
+The last option available to you as a user is template
+qualifiers. These only work if the subtemplate supports them, but they
+allow you to pass additional information in a concise way:
+
+[source,shell]
+----
+lazybones generate artifact::controller
+----
+
+In this case, the template name is `artifact`, but we have qualified
+it with an extra controller. You can pass in as many qualifiers as you
+want, you just separate them with `::`.
+
+Note that you do not specify a version with the `generate`
+command. This is because the subtemplates are embedded directly in the
+project template, and so there can only be one version available to
+you.
\ No newline at end of file
diff --git a/lazybones-docs/src/docs/asciidoc/templates_development.adoc b/lazybones-docs/src/docs/asciidoc/templates_development.adoc
new file mode 100644
index 0000000..12a5a4a
--- /dev/null
+++ b/lazybones-docs/src/docs/asciidoc/templates_development.adoc
@@ -0,0 +1,783 @@
+== Templates
+
+Lazybones alone is just a tool that doesn't do much. It needs a solid
+selection of template packages to make it a compelling solution for
+developers' day-to-day needs. That's why we try to make it as easy as
+possible to develop and publish templates. This guide explains how to
+go about both steps.
+
+=== Getting started
+
+The first thing you want to do is set up a build for your templates,
+because creating and publishing a template involves several steps:
+
+1. Create the directory structure and files for the template
+2. Add VERSION and README files
+3. Package the template structure into a zip, filtering out .retain
+and VERSION files
+4. Publish the zip file to a repository (only Bintray supported at the
+moment)
+5. Fortunately this is dead easy because you can use Lazybones to set
+a project up for you! Simply run
+
+[source,shell]
+----
+lazybones create lazybones-project my-lzb-templates
+----
+
+and you'll get a simple http://gradle.org/[Gradle] build file with a
+directory into which you put your templates. The next step is to
+create the template.
+
+=== Create a template
+
+Lazybones templates are simple zip files containing a directory
+structure and a bunch of files. How you create that zip file is up to
+you, but we're going to use the build that was created for us. It
+handles both the packaging and publishing of templates, so we don't
+have to worry about the details.
+
+So let's create a new template Java project with just a Gradle build
+file and some standard directories. First, create the directory
+`templates/simple-java/`. This is where our template files are going
+to go. Inside this new directory, add these files:
+
+* README.md - a text file that contains information about the template
+* VERSION - a text file containing the current version number of the template
+* build.gradle - the build file for building this new project
+* src/main/java/.retain
+* src/main/resources/.retain
+* src/test/java/.retain
+* src/test/resources/.retain
+
+The `.retain` files allow us to include empty directories in both a
+git repository and the template zip. The build simply excludes
+`.retain` files when packaging the template while maintaining the
+directory structure. Note that the `.retain` files can be empty, so a
+simple `touch` `src/main/java/.retain` is sufficient.
+
+The `build.gradle` file is part of this template project and just
+contains:
+
+[source,groovy]
+----
+apply plugin: "java"
+
+group = "org.example"
+version = "0.1"
+
+repositories {
+ mavenCentral()
+}
+
+dependencies {
+}
+----
+
+The `VERSION` file is required by the build, because that's how the
+build knows what the current version of the template is. Just put any
+version string into the file:
+
+[source,shell]
+----
+1.0-SNAPSHOT
+----
+
+No quotes. No markup. Just the version text. Note that the build
+excludes this file from the template zip as the version is included in
+the zip file's name.
+
+Finally, `README.md` contains some information about the
+template. Remember that this is displayed immediately after a new
+project is created from the template, so it should offer some guidance
+on what the template provides and what steps to take next with the new
+project. Add this to the file:
+
+[source,shell]
+----
+Simple Java project template
+------------------------------
+
+You have just created a basic Java application. It provides a standard
+project structure and a basic Gradle build. Simply add your source files
+to `src/main/java`, your test cases to `src/test/java` and then you will
+be able to build your project with
+
+ gradle build
+ gradle compile
+ gradle test
+
+Don't forget to add any extra JAR dependencies to `build.gradle`!
+----
+
+Although the README is not required, you really should include one. It
+doesn't have to be Markdown either or have a file extension. We just
+happen to like the Markdown syntax and the way that GitHub handles
+files with an md extension.
+
+We could simply leave the template as it is, but wouldn't it be great
+if the user could set the group ID and version for the project at
+creation time? That would mean parameterising the group and version in
+the build file. Not a problem: we can add a post-install script.
+
+=== Create a post-install script
+
+Post-install scripts are executed immediately after a template is
+unpacked into the new project directory and just before the README is
+displayed. They are straight Groovy scripts with access to just the
+core Groovy classes, plus Groovy's `SimpleTemplateEngine` and
+http://commons.apache.org/proper/commons-io/[Apache Commons IO] (for
+making file manipulation easier).
+
+Every script has access to the following properties:
+
+* `projectDir` - (v0.7+) a `File` instance representing the root
+ directory of the new project. Treat this as read-only.
+* `targetDir` - (deprecated) a string representing the root directory
+ of the new project. Use this for versions of Lazybones prior to
+ 0.7. Treat as read-only.
+* `fileEncoding` - the encoding used by your template files. You can
+ set this at the start of the script. Defaults to UTF-8.
+* `lazybonesVersion` - a string representing the version of Lazybones
+ the user is running.
+* `lazybonesMajorVersion` - a string representing the first number in
+ the version string, e.g. "1" for "1.2.3".
+* `lazybonesMinorVersion` - a string representing the second number in
+ the version string, e.g. "2" for "1.2.3".
+
+The script also has access to all the public and protected methods and
+properties defined in the
+https://github.com/pledbrook/lazybones/blob/master/lazybones-app/src/main/groovy/uk/co/cacoethes/lazybones/LazybonesScript.groovy[LazybonesScript]
+class. Of particular interest are the `ask()` and `processTemplates()`
+methods.
+
+`ask()` allows the script to request input from a user, such as 'y' or
+'n' for whether to include a particular feature or not. Even better,
+the user can provide the input on the command line, bypassing the
+input requests all together.
+
+`processTemplates()` makes it easy to parameterise any of the files in
+your template using Groovy syntax. It basically runs the source file
+through Groovy's `SimpleTemplateEngine` to produce the resulting
+file. So if we want to allow the user to specify the project's group
+ID and version at install time, we modify `build.gradle` slightly:
+
+[source,groovy]
+----
+apply plugin: "java"
+
+group = "${group}"
+version = "${version}"
+
+repositories {
+ mavenCentral()
+}
+
+dependencies {
+}
+----
+
+and then add a post-install script, lazybones.groovy, in the root of
+the template:
+
+[source,groovy]
+----
+def props = [:]
+props.group = ask("Define value for 'group' [org.example]: ", "org.example", "group")
+props.version = ask("Define value for 'version' [0.1]: ", "0.1", "version")
+
+processTemplates "build.gradle", props
+----
+
+Sorted! And if the user wants to bypass the two asks, he or she can
+provide values for the requested properties on the command line:
+
+[source,shell]
+----
+lazybones create simple-java my-java-app -Pgroup=uk.co.cacoethes -Pversion=1.0-SNAPSHOT
+----
+
+In other words, you get non-interactive creation of projects from
+templates.
+
+Another useful method available to post-install scripts is
+`transformText()`. It's common for scripts to convert strings between
+camel case (for class names perhaps), lower-case hyphenated (for
+directory names), and other forms. The `transformText()` method allows
+you to do just that:
+
+[source,groovy]
+----
+import uk.co.cacoethes.util.NameType
+
+def className = "MyClass"
+def directoryForClass = transformText(className, from: NameType.CAMEL_CASE, to: NameType.HYPHENATED)
+new File(directoryForClass).mkdirs()
+----
+
+The `from` and `to` arguments are both required and must be one of the
+`NameType` enum values: `CAMEL_CASE` ("MyClass"), `PROPERTY`
+("myClass"), `HYPHENATED` ("my-class"), or `NATURAL` ("My Class")
+
+Once the template is ready, it's time to try it out and publish it.
+
+=== Package, install and publish
+
+There are three steps to publishing a template, each of which can be accomplished with a simple task provided by the build:
+
+* `packaging` - zipping up the template directory
+* `installing` - putting the template package into the local Lazybones
+ template cache
+* `publishing` - making the template package available publicly in a
+ Bintray repository
+
+The relevant Gradle tasks are:
+
+* `packageTemplate`
+* `packageAllTemplates`
+* `installTemplate`
+* `installAllTemplates`
+* `publishTemplate`
+* `publishAllTemplates`
+
+The packaging tasks aren't often used, so we'll skip over those right
+now. But installing the templates in your local cache is important so
+that you can easily test them before publication. You can do this on a
+per-template basis, or simply install all the templates in your
+templates directory.
+
+So if you want execute a task for a particular template, what is
+`` in the above tasks? It's derived from the name of the
+template, which comes from the directory name. In our case, the
+template name is simple-java. To use this name in the Gradle tasks, we
+simply camel-case it: SimpleJava. Of course, this means your
+directories should use hyphenated notation rather than camel-case.
+
+Installing the `simple-java` template in the local cache then becomes a
+case of
+
+[source,shell]
+----
+./gradlew installTemplateSimpleJava
+----
+
+which can then be tested with
+
+[source,shell]
+----
+lazybones create simple-java 1.0-SNAPSHOT my-java-app -Pgroup=uk.co.cacoethes -Pversion=0.1
+----
+
+Note that you have to specify the version of the template to install,
+otherwise Lazybones will look up the latest version online and either
+say the template doesn't exist, or use whatever the latest version is
+(not your development version).
+
+If the rules for converting between camel-case and hyphenated forms
+don't suit your template name, for example if you separate numbers
+with hyphens ('javaee-7'), then you can use hyphens in the task name:
+
+[source,shell]
+----
+./gradlew packageTemplate-javaee-7
+----
+
+Once you're happy with the template, you can publish it to a Bintray
+repository. To do that, you have to configure the build. If you have a
+look at `build.gradle`, you'll see this section (+ some comments):
+
+[source,groovy]
+----
+lazybones {
+ // Pre version 1.1 of the Lazybones Gradle plugin, you needed
+ // to specify this property:
+ // repositoryUrl = "https://api.bintray.com/content//"
+ // instead of `repositoryName`
+ repositoryName = "/" // e.g. "pledbrook/lazybones-templates"
+ repositoryUsername = "your_bintray_username"
+ repositoryApiKey = "your_bintray_api_key"
+
+ // These are required for open source packages
+ licenses = ["Apache-2.0"]
+ vcsUrl = "https://github.com/pledbrook/lazybones/tree/master/lazybones-templates"
+}
+----
+
+As you can see, the repository name, username, and API key properties
+need to be set up properly. You can hard-code the repository name in
+the build file (just replace `` and `` appropriately),
+but the username and API key shouldn't be included in a file that will
+probably go into version control.
+
+Instead, create a `gradle.properties` file in the root of the project
+(not the root of the `simple-java` template, but the overall project
+directory) and put the following into it:
+
+[source,groovy]
+----
+bintrayUsername=someone
+bintrayApiKey=sfhakfh2948th9ghagh4gh30948g93hg
+----
+
+Of course, put your actual username and key in there! Then update
+build.gradle with:
+
+[source,groovy]
+----
+lazybones {
+ repositoryName = "..."
+ repositoryUsername = project.bintrayUsername
+ repositoryApiKey = project.bintrayApiKey
+}
+----
+
+So now the repository credentials are being initialised from the
+(non-SCM-controlled) properties file.
+
+Bintray adds a couple of extra restrictions on publishing if you are
+using the open source hosting. If that's the case, you will need to
+add `licenses` and `vcsUrl` properties to the Lazybones configuration
+block. The assumption here is that all templates in a project are
+licensed under the same OSS licence and the `vcsUrl` property points
+to the host source repository for the whole project.
+
+Before you can successfully publish to Bintray, you of course have to
+have an account. You also have to set up a repository, which you can
+do through the Bintray web UI. Once that's done, you can run
+
+[source,shell]
+----
+./gradlew publishTemplateSimpleJava
+----
+
+to make it available to all and sundry! Don't forget to go to the
+Bintray UI in order to finalise the publication. You can also send an
+inclusion request for your package to
+`pledbrook/lazybones-templates`. If accepted, your template will
+automatically appear in the `lazybones list` command.
+
+=== Fine-tuning the packaging
+
+**(since version 1.2 of the Gradle plugin)**
+
+The packaging process is by default rather dumb. It will include all
+files and directories in the target template directory except for a
+few hard-coded exceptions (the VERSION and .retain files for
+example). That leaves a lot of scope for accidentally including
+temporary files in the package! To help you avoid that, the plugin
+allows you to specify a set of extra exclusions using Ant-style paths:
+
+[source,groovy]
+----
+lazybones {
+ packageExclude "**/*.swp", ".gradle", "build"
+}
+----
+
+These exclusions apply to all templates. If you want template-specific
+exclusions, then use the following syntax:
+
+[source,groovy]
+----
+lazybones {
+ template("simple-java") { // Template (directory) name
+ packageExclude "**/*.swp", ".settings"
+ }
+}
+----
+
+Note that the template-specific settings completely override the
+global ones, so if you want the global ones to apply you will need to
+repeat them in the template-specific list.
+
+Another potential issue when packaging templates is with file and
+directory permissions. Lazybones attempts to retain the permissions it
+finds in the template directory, but these may not be correct on
+Windows. To compensate for that, the plugin allows you to specify file
+permissions in the template configuration:
+
+[source,groovy]
+----
+lazybones {
+ fileMode "755", "gradlew", "**/*.sh"
+}
+----
+
+The first argument is the Unix-style permission as a string (such as
+`"600"`, `"755"` and so on), and the rest are a list of Ant-style
+patterns representing the files and directories that the permission
+string should apply to. You can have multiple `fileMode()` entries,
+although ideally you should only have one per file mode.
+
+As with package exclusions, you can also specify file modes on a
+per-template basis:
+
+[source,groovy]
+----
+lazybones {
+ template("simple-java") {
+ fileMode "600", "secret.properties"
+ fileMode "755, "gradlew", "**/*.sh"
+ }
+}
+----
+
+Again, the template-specific settings replace the global ones for that
+particular template.
+
+That's it for the getting started guide. You've created a template,
+tested it, and finally published it to Bintray. For the rest of the
+guide we'll look at the template creation in more detail.
+
+=== Template engines
+
+The `processTemplates()` method available to post-install scripts
+allows you to generate files based on templates. By default, any files
+that match the pattern passed to `processTemplates()` are treated as
+Groovy templates that can be processed by
+http://docs.groovy-lang.org/latest/html/api/groovy/text/SimpleTemplateEngine.html[SimpleTemplateEngine]
+and those source files are replaced by the processed versions. That's
+not the end of the story though.
+
+Lazybones allows you to use any template engine that implements
+Groovy's
+http://docs.groovy-lang.org/latest/html/api/groovy/text/TemplateEngine.html[TemplateEngine],
+meaning that your source templates could be Moustache, Velocity, or
+anything else. Of course, not every template engine has a Groovy
+implementation but it's often trivial to create an adapter
+`TemplateEngine` implementation. For the following examples, we'll use
+a Handlebars implementation.
+
+The first step to using an alternative template engine is to include
+the implementation JAR in the post-install script for your project
+template. Lazybones uses Groovy's `@Grab` annotation for that:
+
+[source,groovy]
+----
+@Grab(group="uk.co.cacoethes", module="groovy-handlebars-engine", version="0.2")
+import uk.co.cacoethes.handlebars.HandlebarsTemplateEngine
+
+registerDefaultEngine new HandlebarsTemplateEngine()
+----
+
+The Handlebars engine JAR is in
+https://bintray.com/bintray/jcenter[jCenter] which @Grab automatically
+searches along with Maven Central. If you have the JAR hosted
+elsewhere, you'll need to use
+http://docs.groovy-lang.org/latest/html/api/groovy/lang/GrabResolver.html[@GrabResolver].
+
+Once you have the JAR on the script's classpath, you can register the
+engine. There are several ways to do this depending what you want to
+do. The above example uses `registerDefaultEngine()` to make the
+Handlebars template engine the default, which means that any files
+handled by `processTemplates` will be treated as Handlbars templates
+rather than Groovy ones.
+
+What if you want to use different engines for different templates
+though? Or perhaps you prefer to give the source templates a suffix
+that identifies them as such? In these cases, you can use
+`registerEngine()`:
+
+[source,groovy]
+----
+@Grab(group="uk.co.cacoethes", module="groovy-handlebars-engine", version="0.2")
+import uk.co.cacoethes.handlebars.HandlebarsTemplateEngine
+
+registerEngine "hbs", new HandlebarsTemplateEngine()
+
+processTemplates "**/*.groovy", [foo: "bar"]
+----
+
+This method registers a template engine against a specific suffix. If
+any files match the `processTemplates()` pattern with the addition of
+the registered suffix, Lazybones will use the corresponding template
+engine for that file.
+
+So let's say your template project has a
+`src/main/groovy/org/example/App.groovy.hbs` file. The App.groovy part
+matches the pattern and `hbs` is a registered extension. So that file
+will be processed by the Handlebars template engine, creating a
+`src/main/groovy/org/example/App.groovy` file in the target
+project. Here's a summary of how source template files are processed:
+
+[cols="3"]
+|===
+|Filename |Resulting file |Processing
+|App.groovy |App.groovy |Registered default template engine
+|App.groovy.gtpl |App.groovy |Groovy template engine
+|App.groovy.hbs |App.groovy |Handlebars template engine
+|===
+
+Lazybones automatically registers the Groovy template engine against
+the suffix `gtpl`. Also note that you should not include the template
+suffix in your file pattern. If you try
+
+[source,groovy]
+----
+processTemplates "**/*.hbs", [foo: "bar"]
+----
+
+then Lazybones will in fact use the default template engine for any
+source file that has an `hbs` suffix. It's better to use the pattern
+
+[source,groovy]
+----
+"**/*"
+----
+
+instead, as then any files ending with `hbs` will be processed with the
+Handlebars template engine. This does raise a problem: the pattern
+above will match non-template files too, and Lazybones will process
+those files with the default template engine.
+
+If you do want to take this approach, then you can disable the default
+template engine:
+
+[source,groovy]
+----
+@Grab(group="uk.co.cacoethes", module="groovy-handlebars-engine", version="0.2")
+import uk.co.cacoethes.handlebars.HandlebarsTemplateEngine
+
+registerEngine "hbs", new HandlebarsTemplateEngine()
+clearDefaultEngine()
+
+processTemplates "**/*", [foo: "bar"]
+----
+
+This will ensure that only source files with a registered template
+suffix get processed. All other files are left untouched.
+
+=== Subtemplates
+
+**(since 0.7)**
+
+As long as you are using version 1.1 or later of the Lazybones Gradle
+plugin, it's very easy to add subtemplate support to your project
+templates. The key points to understand are:
+
+* Subtemplates are similar to project templates but packaged inside a
+ project template zip
+* A subtemplate can be included in multiple project templates
+* Subtemplates only take effect when the user runs the `lazybones
+ generate` command
+
+Let's say you want to add a subtemplate for generating `@Entity`
+classes in a project created from the simple-java template we
+introduced earlier. Your starting point is to create a new directory
+for the subtemplate:
+
+[source,groovy]
+----
+templates/subtmpl-entity
+----
+
+Note that although the subtemplate will be going inside the
+simple-jave template, its directory is at the same level as
+templates/simple-java. The key is to give the directory name as
+'subtmpl-' prefix, as this is what tells the build that it's a
+subtemplate, resulting in subtmpl-entity being excluded from the
+*AllTemplates tasks.
+
+The contents of a subtemplate source directory look a little like a
+normal project template, except you are unlikely to include as many
+files and the README is unnecessary. In this case, we want:
+
+* `VERSION` - the file containing the current version of the subtemplate
+* `lazybones.groovy` - the post-install script
+* `Entity.groovy.gtpl` - the template source file for entity classes
+
+Each of these files behaves in the same way as in a project template,
+but there are a few subtleties. Consider the template source file for
+entities:
+
+[source,groovy]
+----
+package ${pkg}
+
+import grails.persistence.Entity
+
+@Entity(group="${parentGroup}", version="${parentVersion}")
+class ${cls} {
+ String name
+}
+----
+
+This references several parameters: `pkg`, `cls`, `parentGroup` and
+`parentVersion`. Where do these parameters come from? We need to look
+into the post-install script, lazybones.groovy, to find out:
+
+[source,groovy]
+----
+import org.apache.commons.io.FileUtils
+import org.apache.commons.io.FilenameUtils
+
+import static org.apache.commons.io.FilenameUtils.concat
+
+def params = [:]
+params.pkg = ask("Define value for the package: ", null, "package")
+params.cls = ask("Define value for class name: ", null, "class").capitalize()
+
+// Pass in parameters from the project template
+params.parentGroup = parentParams.group
+params.parentVersion = parentParams.version
+
+processTemplates("Entity.groovy", params)
+
+def pkgPath = params.pkg.replace('.' as char, '/' as char)
+def filename = params.cls + ".groovy"
+def destFile = new File(projectDir, concat(concat("src/main/groovy", pkgPath), filename))
+destFile.parentFile.mkdirs()
+
+FileUtils.moveFile(new File(templateDir, "Entity.groovy"), destFile)
+
+println "Created new persistence entity ${FilenameUtils.normalize(destFile.path)}"
+----
+
+As you can see, the `pkg` and `cls` parameters are mapped from the
+return values of two `ask()` calls. This is standard post-install
+script behaviour. The interesting parameters, `parentGroup` and
+`parentVersion`, are mapped from something new: the `parentParams`
+map. This contains any named parameters used by the parent project
+template, i.e. simple-java in this case. Because of this,
+`parentParams` only exists for subtemplates.
+
+Another novel aspect of the post-install script is the reference to a
+`templateDir` property in addition to `projectDir`. This is because
+subtemplates are not unpacked directly in the project
+directory. Instead, Lazybones unpacks them into the project's
+.lazybones directory. `templateDir` points to the location of the
+unpacked subtemplate, whereas `projectDir` still points to the root
+directory of the project created from simple-java. So your subtemplate
+post-install script will typically want to copy or move files from
+`templateDir` to `projectDir`. The Commons IO classes that all
+post-install scripts have access to are ideal for this.
+
+With all of the subtemplates files in place, all you need to do is
+tell the build that the simple-java project template should include
+the entity subtemplate. So open up the build file and add this line to
+the `lazybones` block:
+
+[source, groovy]
+----
+lazybones {
+ ...
+ template "simple-java" includes "entity"
+}
+----
+
+Note how the name of the subtemplate excludes the 'subtmpl-'
+prefix. Now when you package the simple-java project template, the
+entity subtemplate will be included in it, ready for use with
+Lazybones' `generate` command.
+
+If you want to include multiple subtemplates, just pass extra
+arguments to `includes()`:
+
+[source,groovy]
+----
+lazybones {
+ ...
+ template "simple-java" includes "entity", "controller", "view"
+}
+----
+
+There is one final option available to template authors. What if you
+want to package the entity, controller, and view template files into a
+single subtemplate package? How would the user be able to specify
+which type of class he or she wants to generate? The answer is through
+template qualifiers.
+
+Let's say you have an 'artifact' subtemplate that includes
+Entity.groovy.gtpl, Controller.groovy.gtpl, etc. The user can run the
+`generate` command like this to determine which artifact type to use:
+
+[source,shell]
+----
+lazybones generate artifact::controller
+----
+
+The `::` separates the subtemplate name, 'artifact', from the qualifier,
+'controller'. In your post-install script, you can access the
+qualifiers through a `tmplQualifiers` property:
+
+[source,groovy]
+----
+def artifactTemplate
+if (tmplQualifiers) {
+ artifactTemplate = tmplQualifiers[0].capitalize() + ".groovy.gtpl"
+}
+else {
+ artifactTemplate = ask("Which type of artifact do you want to generate? ", null, "type")
+}
+
+// ... process the corresponding template file.
+----
+
+The user can even pass extra qualifiers simply by separating them with
+`::`
+
+[source,shell]
+----
+lazybones generate artifact::controller::org.example::Book
+----
+
+This is why `tmplQualifiers` is a list. It retains the order that the
+qualifiers are specified on the command line.
+
+Note qualifiers should not be used for general parameterisation such
+as packages and class names. Think carefully before supporting more
+than a single qualifier.
+
+=== Post install script in-depth
+
+The lazybones.groovy post install script is a generic groovy script
+with a few extra helper methods:
+
+* `ask(String message, defaultValue = null)` - asks the user a
+ question and returns their answer, or `defaultValue` if no answer is
+ provided
+
+* `ask(String message, defaultValue, String propertyName)` - works
+ similarly to the `ask()` above, but allows grabbing variables from the
+ command line as well based on the `propertyName`.
+
+* `processTemplates(String filePattern, Map substitutionVariables)` -
+ use ant pattern matching to find files and filter their contents in
+ place using Groovy's `SimpleTemplateEngine`.
+
+* `hasFeature(String featureName)` - checks if the script has access
+ to a feature, `hasFeature("ask")` or
+ `hasFeature("processTemplates")` would both return true
+
+You can get a complete list of the available methods from the
+https://github.com/pledbrook/lazybones/blob/master/lazybones-app/src/main/groovy/uk/co/cacoethes/lazybones/LazybonesScript.groovy[LazybonesScript]
+class.
+
+Here is a very simple example `lazybones.groovy` script that asks the
+user for a couple of values and uses those to populate parameters in
+the template's build file:
+
+[source,groovy]
+----
+def params = [:]
+params["groupId"] = ask("What is the group ID for this project?")
+params["version"] = ask("What is the project's initial version?", "0.1", "version")
+
+processTemplates("*.gradle", params)
+processTemplates("pom.xml", params)
+----
+
+The main Gradle build file might then look like this:
+
+[source,groovy]
+----
+apply plugin: "groovy"
+
+<% if (group) { %>group = "${group}"<% } %>
+version = "${version}"
+----
+
+The `${}` expressions are executed as Groovy expressions and they have
+access to any variables in the parameter map passed to
+`processTemplates()`. Scriptlets, i.e. code inside `<% %>` delimiters,
+allow for more complex logic.
\ No newline at end of file
diff --git a/lazybones-docs/src/docs/asciidoc/templates_search.adoc b/lazybones-docs/src/docs/asciidoc/templates_search.adoc
new file mode 100644
index 0000000..0b937e3
--- /dev/null
+++ b/lazybones-docs/src/docs/asciidoc/templates_search.adoc
@@ -0,0 +1,29 @@
+== Search Templates
+
+To see what templates you can install, run
+
+[source,shell]
+----
+lazybones list
+----
+
+This will list all aliases and remote templates. If you want to see
+what templates you have cached locally, run
+
+[source,shell]
+----
+lazybones list --cached
+----
+
+In fact, `--cached` is implied if Lazybones can't connect to the internet.
+
+You can also find out more about a template through the info command:
+
+[source,shell]
+----
+lazybones info
+----
+
+This will print a description of the template and what versions are
+available for it. If you're offline, this will simply display an error
+message.
\ No newline at end of file
diff --git a/lazybones-templates/templates.gradle b/lazybones-templates/templates.gradle
index f637fea..b5e319b 100644
--- a/lazybones-templates/templates.gradle
+++ b/lazybones-templates/templates.gradle
@@ -29,11 +29,21 @@ gradle.taskGraph.whenReady { graph ->
if (graph.allTasks.any { it.name.startsWith("publish") }) {
verifyProperty(project, 'repo.username')
verifyProperty(project, 'repo.apiKey')
+ verifyProperty(project, 'github.token')
graph.allTasks.findAll { it instanceof BintrayGenericUpload }.each { task ->
task.username = project.'repo.username'
task.apiKey = project.'repo.apiKey'
}
+
+ graph.allTasks.findAll { it.name == 'publishGhPages' }.each { task ->
+ task.project.githubPages.credentials.with {
+ username = project.'github.token'
+ //Password should be set in blank when using github token
+ //https://github.com/ajoberstar/gradle-git/wiki/Travis-CI-Authentication
+ password = ''
+ }
+ }
}
}
diff --git a/settings.gradle b/settings.gradle
index 7cbf960..6ba3b22 100644
--- a/settings.gradle
+++ b/settings.gradle
@@ -1,6 +1,7 @@
include "lazybones-gradle-plugin",
"lazybones-templates",
- "lazybones-app"
+ "lazybones-app",
+ "lazybones-docs"
rootProject.name = "lazybones"
+
Lazybones was born out of frustration that [Ratpack](https://ratpack.io)
does not and will not have a command line tool that will bootstrap a project.
It's a good decision for Ratpack, but I'm lazy and want tools to do the boring
@@ -17,427 +21,15 @@ does for web applications. Lazybones also includes a subtemplates feature that
resembles the behaviour of Yeoman's sub-generators, allowing you to generate optional
extras (controllers, scaffolding etc.) inside a project.
-[](https://travis-ci.org/pledbrook/lazybones)
-
-## Developers
-
-* [Peter Ledbrook](https://github.com/pledbrook)
-* [Kyle Boon](https://github.com/kyleboon)
-* [Tommy Barker](https://github.com/tbarker9)
-
-## Contributors
-
-* [Luke Daley](https://github.com/alkemist)
-* [Tomas Lin](https://github.com/tomaslin)
-* [Russell Hart](https://github.com/rhart)
-* [Dave Syer](https://github.com/dsyer)
-* [Andy Duncan](https://github.com/andyjduncan)
-
-
-## Running it
-
-Grab lazybones from [sdkman](http://sdkman.io/) (formerly gvm):
-
- sdk install lazybones
-
-or alternatively, grab the distribution [from Bintray](https://bintray.com/pkg/show/general/pledbrook/lazybones-templates/lazybones),
-unpack it to a local directory, and then add its 'bin' directory to your `PATH`
-environment variable.
-
-### Creating projects
-
-To create a new project, run
-
- lazybones create