Commits

David Carr committed bd61085

docs: add README

Comments (0)

Files changed (1)

+# Overview
+The Jayne Site project is a [Gradle](http://www.gradle.org/) plugin for publishing static HTML websites.  It is available for use under the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0).
+
+# Distribution
+The plugin is distributed via [Bintray](https://www.bintray.com/).  If desired, you can use the [Bintray plugin](https://bitbucket.org/davidmc24/gradle-bintray-plugin) to simplify the configuration of Bintray repositories within Gradle build scripts.
+
+# Usage
+To use the plugin, configure your `build.gradle` based the example below.  See the [CHANGES](https://bitbucket.org/davidmc24/jayne-site/src/tip/CHANGES.md) file for a listing of versions.
+
+    :::groovy
+    buildscript {
+        repositories {
+            maven {
+                name = 'BintrayJCenter'
+                url = 'http://jcenter.bintray.com'
+            }
+        }
+        dependencies {
+            classpath 'us.carrclan.david.gradle:jayne-site:VERSION'
+        }
+    }
+    apply plugin: 'jayne-site'
+
+# Source sets
+
+The Jayne Site plugin adds a `site` source set.  This source set works in the same manner as with other plugins.
+
+# Tasks
+
+The Jayne Site plugin adds a couple tasks to your project, as shown below.
+
+Task name              | Depends on                                | Type        | Description
+---------------------- | ----------------------------------------- | ----------- | ---------------------------------------------------------------
+`processSiteResources` | -                                         | Copy        | Copies site resources into the site resources output directory.
+`lessCompileSite`      | -                                         | LessCompile | Compiles the site LESS files.
+`buildSite`            | `processSiteResources`, `lessCompileSite` | Task        | Builds the site.
+`publishSite`          | `buildSite`                               | PublishSite | Uploads the site resources output.
+
+# Project Layout
+
+The Jayne Site plugin assumes the project layout shown below.
+
+Directory            | Meaning
+-------------------- | ---------------
+`src/site/resources` | Site resources
+`src/site/less`      | Site LESS files
+
+## Changing the project layout
+
+You can configure the project layout by configuring the source set.  Below is a brief example that changes the site resources directory to be a direct child of the project root.
+
+### build.gradle
+
+    :::groovy
+    sourceSets {
+        site {
+            resources {
+                srcDir 'website'
+            }
+        }
+    }
+
+# Extension Properties
+
+The Jayne Site plugin adds a `site` extension to the project.  You can use its properties to customize the behavior of the plugin's tasks.
+
+Property name        | Type                 | Default value     | Description
+-------------------- | -------------------- | ----------------- | --------------------------------------------------------------------
+`sourceSet`          | `SourceSet`          | `sourceSets.site` | The source set to use for site tasks.
+`url`                | `String`             | None              | The URL to which the site should be published.
+`authenticationInfo` | `AuthenticationInfo` | None              | The authentication information with to use when publishing the site.
+
+## Configuration Example
+
+### build.gradle
+
+    :::groovy
+    site {
+        url = 'sftp://ftp.example.com/joe'
+        authenticationInfo {
+            userName = 'joe'
+            password = 'secretPassword'
+        }
+    }
+
+# ProcessSiteResources
+
+The Site plugin uses the [Copy](http://www.gradle.org/docs/current/dsl/org.gradle.api.tasks.Copy.html) task for resource handling.  See the [Gradle User Guide](http://www.gradle.org/docs/current/userguide/userguide.html) for more information.
+
+Task Property    | Type     | Default Value
+---------------- | -------- | -----------------------------------
+`srcDirs`        | `Object` | `site.sourceSet.resources`
+`destinationDir` | `File`   | `site.sourceSet.output.resourceDir`
+
+# PublishSite
+
+The Site plugin uses [Maven Wagon](https://maven.apache.org/wagon/) to provide site publishing capability over a number of different protocols.  Currently, only the SFTP provider has been tested, though others (HTTP, FTP, SCP, WebDAV, file) may work as well.
+
+Task Property        | Type                 | Default Value
+-------------------- | -------------------- | -----------------------------------
+`baseDir`            | `File`               | `site.sourceSet.output.resourceDir`
+`url`                | `String`             | `site.url`
+`authenticationInfo` | `AuthenticationInfo` | `site.authenticationInfo`
+
+# LessCompile
+
+The plugin introduces a new task type, `LessCompile`, which performs LESS compilation using [lesscss-java](https://github.com/marceloverdijk/lesscss-java).
+
+Task Property    | Type      | Description
+---------------- | --------- | ---------------------------------------------------
+`sourceDir`      | `Object`  | The path to the LESS source files to compile.
+`destinationDir` | `File`    | The destination for the compiled CSS files.
+`encoding`       | `String`  | The encoding with with to write the CSS files.
+`compress`       | `Boolean` | Whether to enable the LESS compiler's minification.
+
+## Task Defaults: lessCompileSite
+
+Task Property    | Type      | Default Value
+---------------- | --------- | -----------------------------------
+`sourceDir`      | `Object`  | `"src/site/less"`
+`destinationDir` | `File`    | `"${site.sourceSet.output.resourceDir}/css"`
+`encoding`       | `String`  | None
+`compress`       | `Boolean` | None