Readme Gradle Plugin

This plugin provides functionality to generate a projects README.textile and README.html as part of the Gradle build using the WikiText project.
The plugin is fully configurable and provides functionality for binding dynamic template variables to the README.textile.

Contents

1. Installation
2. Quick Start
3. Convention Properties
4. Including CSS Stylesheets
5. Template Variable Binding

Installation

To create the plugin jar do

gradle

The jar wil be created under build/lib

Quick Start

build.gradle

buildscript {
    dependencies {
        classpath files('lib/readme.jar')
    }
}

apply plugin: 'readme'

//build logic...

Put the README.textile template in a directory under the root of the project called readme

.
|-- lib/readme.jar
`-- readme
    `--README.textile

To create the README.textile and README.html at the root of the project, do

gradle createReadme

Convention Properties

The plugin associates a convention object with the project called readme. This can be configured as follows

readme {
    src = 'src/path' // Directory containing the source of the README.textile. Defaults to 'readme'
    dest = 'dest/path' // The destination for the generated README.html.  Defaults to '.'
    stylesheets // List of stylesheet URLs to link to in from README.html.
    templateVars // Template variables with Groovy's SimleTemplateEngine.
}

Inluding CSS Stylesheet

The stylesheets convention property is a list of Strings representing URLs to CSS stylesheets.
Stylesheets are placed into generated README.html.

Template Variable Binding

The plugin uses the expand method of Gradle’s copy task to parse the README.textile in src with Groovy’s SimpleTemplateEngine.

Template variables can be defined in the following ways:

As direct properties

templateVars.x = y
templateVars.a.b = c

As groovy config

templateVars << CONFIG

CONFIG is either an instance of java.util.String, java.io.File or java.net.URL and represents the location of a Groovy script.
This script is parsed as a ConfigObject and merged into templateVars.

Properties referenced that do not exist will be ignored.

The Gradle project instance is automatically made available as a template variable and cannot be reassigned.