Add initial docs

README.md

@@ -1,7 +1,35 @@
-# sbt-dependency-lock
+# sbt-dependency-lock 
+[![Build Status](https://travis-ci.com/stringbean/sbt-dependency-lock.svg?branch=master)](https://travis-ci.com/stringbean/sbt-dependency-lock)
+[![Codacy grade](https://img.shields.io/codacy/grade/d45ca406c90c45c88a3a317563bc3302?label=codacy)](https://codacy.com/app/stringbean/sbt-dependency-lock)
+![Bintray](https://img.shields.io/bintray/v/stringbean/sbt-plugins/sbt-dependency-lock?label=sbt%201.x) 
 
-An sbt plugin to create a dependency lockfile
+An sbt plugin to create a dependency lockfile similar to `package-lock.json` for npm or `Gemfile.lock` for RubyGems.
 
-## Usage
+## Quickstart
 
-This plugin requires sbt 1.0.0+
+Install the plugin by adding the following to `project/plugins.sbt`:
+
+```scala
+addSbtPlugin("software.purpledragon" % "sbt-dependency-lock" % "<version>")
+```
+
+And then generate a lock file with `sbt dependencyLockWrite`. This will resolve dependencies and output a lockfile
+containing all dependencies (including transitive ones) to `build.sbt.lock`.
+
+The lockfile can then be checked with `sbt dependencyLockCheck`:
+
+```text
+[info] Dependency lock check passed
+```
+
+A mismatch between the lockfile and current dependencies will generate an error report:
+
+```text
+[error] (dependencyLockCheck) Dependency lock check failed:
+[error]   3 dependencies changed:
+[error]     org.scala-lang.modules:scala-xml_2.12:[1.2.0]->[1.1.0] (test)
+[error]     org.scalactic:scalactic_2.12:[3.0.8]->[3.0.7] (test)
+[error]     org.scalatest:scalatest_2.12:[3.0.8]->[3.0.7] (test)
+```
+
+See the [docs](https://stringbean.github.io/sbt-dependency-lock) for further information on how the plugin works.

build.sbt

@@ -1,7 +1,10 @@
 name := "sbt-dependency-lock"
 organization := "software.purpledragon"
 
-enablePlugins(SbtPlugin)
+enablePlugins(
+  SbtPlugin,
+  ParadoxSitePlugin,
+  GhpagesPlugin)
 
 // target sbt 1.2.8 to allow 1.0+ compatibility
 pluginCrossBuild / sbtVersion := "1.2.8"
@@ -37,6 +40,7 @@ scmInfo := Some(
   ScmInfo(
     url("https://github.com/stringbean/sbt-dependency-lock"),
     "https://github.com/stringbean/sbt-dependency-lock.git"))
+git.remoteRepo := "git@github.com:stringbean/sbt-dependency-lock.git"
 
 bintrayPackageLabels := Seq("sbt", "sbt-plugin", "lockfile")
 
@@ -54,6 +58,7 @@ releaseProcess := Seq[ReleaseStep](
   commitReleaseVersion,
   tagRelease,
   publishArtifacts,
+  releaseStepTask(ghpagesPushSite),
   setNextVersion,
   commitNextVersion,
   pushChanges

project/plugins.sbt

@@ -1,6 +1,13 @@
+// publishing
 addSbtPlugin("com.jsuereth" % "sbt-pgp" % "1.1.1")
 addSbtPlugin("org.foundweekends" % "sbt-bintray" % "0.5.4")
 addSbtPlugin("com.github.gseitz" % "sbt-release" % "1.0.12")
 
+// code style
 addSbtPlugin("de.heikoseeberger" % "sbt-header" % "5.2.0")
-addSbtPlugin("com.sksamuel.scapegoat" %% "sbt-scapegoat" % "1.0.9")
+addSbtPlugin("com.sksamuel.scapegoat" %% "sbt-scapegoat" % "1.0.9")
+
+// documentation
+addSbtPlugin("com.typesafe.sbt" % "sbt-site" % "1.4.0")
+addSbtPlugin("com.lightbend.paradox" % "sbt-paradox" % "0.6.8")
+addSbtPlugin("com.typesafe.sbt" % "sbt-ghpages" % "0.6.3")

src/main/paradox/file-formats/index.md

@@ -0,0 +1,15 @@
+# File Formats
+
+_sbt-dependency-lock_ stores lockfile information in JSON format with a version identifier (`lockVersion`) in the
+top-level object. Details of the file format can be found on these pages, and we encourage other tools to utilise the
+output information.
+
+| Version                | Added In | Removed In | Description      |
+| ---------------------: | -------: | ---------: | ---------------- |
+| @ref:[1](version-1.md) |    0.1.0 |  _current_ | Initial version. |
+
+Current default version is: 1
+
+@@@ index
+* [Version 1](version-1.md)
+@@@

src/main/paradox/file-formats/version-1.md

@@ -0,0 +1,132 @@
+# Version 1
+
+@@@warning
+This version of the lockfile has not been finalised and may change as features are added or bugs resolved.
+
+The format will be finalised in version 1.0.0.
+@@@
+
+* **Added in:** 0.1.0
+* **Removed in:** _N/A_
+
+## Types
+
+### Lockfile
+
+Top level object for a project lockfile. Contains details of the build configurations and a list of the resolved
+dependencies.
+
+#### lockVersion
+
+* **Type:** Integer.
+* **Description:** Version of the lockfile - always 1.
+
+#### timestamp
+
+* **Type:** String (timestamp).
+* **Description:** File generation timestamp in ISO 8601 format.
+
+#### configurations
+
+* **Type:** Array of strings.
+* **Description:** List of sbt build configurations in the current project.
+
+#### dependencies
+
+* **Type:** Array of `Dependency`.
+* **Description:** List of all the dependencies in the current project. 
+
+### Dependency
+
+Details of a resolved dependency.
+
+#### org
+
+* **Type:** String.
+* **Description:** Organisation of the resolved dependency from Ivy/Maven.
+
+#### name
+
+* **Type:** String.
+* **Description:** Name of the resolved dependency from Ivy/Maven. 
+
+#### version
+
+* **Type:** String.
+* **Description:** Version of the resolved dependency.
+
+#### artifacts
+
+* **Type:** Array of `Artifact`.
+* **Description:** List of all the artifacts for the dependency.
+* **Note:** Currently only `jar` artifacts are included.
+
+#### configurations
+
+* **Type:** Array of strings.
+* **Description:** List of the sbt configurations that include this dependency.
+
+### Artifact
+
+Details of an artifact contained within a dependency.
+
+#### name
+
+* **Type:** String.
+* **Description:** Filename of the artifact.
+
+#### hash
+
+* **Type:** String (checksum).
+* **Description:** Checksum of the artifact prefixed with the checksum algorithm.
+* **Note:** Currently only `sha1` is supported.
+
+## Example
+
+```json
+{
+  "lockVersion" : 1,
+  "timestamp" : "2019-10-29T17:33:05.944Z",
+  "configurations" : [
+    "compile",
+    "optional",
+    "provided",
+    "runtime",
+    "test"
+  ],
+  "dependencies" : [
+    {
+      "org" : "org.apache.commons",
+      "name" : "commons-lang3",
+      "version" : "3.9",
+      "artifacts" : [
+        {
+          "name" : "commons-lang3.jar",
+          "hash" : "sha1:0122c7cee69b53ed4a7681c03d4ee4c0e2765da5"
+        }
+      ],
+      "configurations" : [
+        "test",
+        "compile",
+        "runtime"
+      ]
+    },
+    {
+      "org" : "org.scala-lang",
+      "name" : "scala-library",
+      "version" : "2.12.10",
+      "artifacts" : [
+        {
+          "name" : "scala-library.jar",
+          "hash" : "sha1:3509860bc2e5b3da001ed45aca94ffbe5694dbda"
+        }
+      ],
+      "configurations" : [
+        "test",
+        "compile",
+        "runtime"
+      ]
+    }
+  ]
+}
+```

src/main/paradox/getting-started.md

@@ -0,0 +1,81 @@
+# Getting Started
+
+## Setup
+
+Install the plugin by adding the following to `project/plugins.sbt`:
+
+@@@vars
+```scala
+addSbtPlugin("software.purpledragon" % "sbt-dependency-lock" % "$project.version$")
+```
+@@@
+
+And then generate a lock file with `sbt dependencyLockWrite`. This will resolve dependencies and output a lockfile
+containing all dependencies (including transitive ones) to `build.sbt.lock`.
+
+@@@ note
+The generated `build.sbt.lock` file should be checked into source control with the rest of the project source code.
+@@@
+
+## Checking for Dependency Changes
+
+The status of the lockfile can be checked using the `dependencyLockCheck` which will resolve the current dependencies
+and check them against the lockfile.
+
+### Valid Lockfile
+
+If the lockfile and current dependencies match then a success message will be printed, and the build will succeed:
+
+```text
+[info] Dependency lock check passed
+```
+
+### Missing Lockfile
+
+If no lockfile can be found then an error will be printed, and the build will fail:
+
+```text
+[error] (dependencyLockCheck) no lock file
+```
+
+### Lockfile Mismatch
+
+A mismatch between the lockfile and current dependencies will generate an error report summarising the differences:
+
+```text
+[error] (dependencyLockCheck) Dependency lock check failed:
+[error]   3 dependencies changed:
+[error]     org.apache.commons:commons-lang3:3.9 (test)->(compile,test)
+[error]     org.scala-lang.modules:scala-xml_2.12:[1.2.0]->[1.1.0] (test)
+[error]     org.scalactic:scalactic_2.12:[3.0.8]->[3.0.7] (test)
+[error]     org.scalatest:scalatest_2.12:[3.0.8]->[3.0.7] (test)
+```
+
+The error report is broken down into a number of sections:
+
+1. Configurations added:
+    ```text
+    1 config added: it
+    ```
+2. Configurations removed:
+    ```text
+    2 configs removed: it,war
+    ```
+3. Dependencies added:
+    ```text
+    2 dependencies added:
+      com.example:artifact1:1.0 (compile)
+      com.example:artifact2:1.2 (test)
+    ```
+4. Dependencies removed:
+    ```text
+    1 dependency removed:
+      com.example:artifact3:3.1.1 (runtime)
+    ```
+5. Changed dependencies:
+    ```text
+    3 dependencies changed:
+      org.example:version:[1.0]->[2.0] (compile)
+      org.example:configs:1.0 (compile,test)->(compile)
+      org.example:both:[1.0]->[2.0] (compile)->(compile,test)
+    ```

src/main/paradox/index.md

@@ -0,0 +1,18 @@
+# sbt-dependency-lock
+
+Generate dependency lockfiles for sbt projects similar to `package-lock.json` or `Gemfile.lock`.
+
+## Rationale
+
+Managing dependencies on a large project can be a difficult problem especially when requested dependencies pull in large
+numbers of transitive dependencies. This can lead to scenarios where incrementing the version of a single dependency can
+cause a snowball effect of dozens of updated transitive dependencies.
+
+This plugin generates a lockfile based on the current project dependencies that can be checked into source control and
+can be checked to see what dependencies have changed. 
+
+@@@ index
+* [Getting Started](getting-started.md)
+* [Settings](settings.md)
+* [File Formats](file-formats/index.md)
+@@@

src/main/paradox/settings.md

@@ -0,0 +1,9 @@
+# Settings Reference
+
+## Settings
+
+### dependencyLockFile
+
+* **Description:** Filename of generated lockfile.
+* **Accepts:** `java.io.File`
+* **Default:** `baseDirectory.value / "build.sbt.lock"`