Switch to sbt-microsites circe#438

CONTRIBUTING.md

@@ -1,3 +1,9 @@
+---
+layout: docs
+title:  "Guide for contributors"
+position: 6
+---
+
 # Guide for contributors
 
 This project follows a standard [fork and pull][fork-and-pull] model for accepting contributions via

build.sbt

@@ -94,14 +94,27 @@ def noDocProjects(sv: String): Seq[ProjectReference] = Seq[ProjectReference](
   }
 )
 
-val docMappingsApiDir = settingKey[String]("Subdirectory in site target directory for API docs")
-val docMappingsTutDir = settingKey[String]("Subdirectory in site target directory for Tut docs")
-
-lazy val docSettings = allSettings ++ tutSettings ++ ghpages.settings ++ unidocSettings ++ Seq(
-  docMappingsApiDir := "api",
-  docMappingsTutDir := "_tut",
-  addMappingsToSiteDir(mappings in (ScalaUnidoc, packageDoc), docMappingsApiDir),
-  addMappingsToSiteDir(tut, docMappingsTutDir),
+lazy val docSettings = allSettings ++ unidocSettings ++ Seq(
+  micrositeName := "Circe",
+  micrositeDescription := "Yet another JSON library for Scala",
+  micrositeAuthor := "Travis Brown",
+  micrositeHighlightTheme := "atom-one-light",
+  micrositeHomepage := "https://travisbrown.github.io/circe/",
+  micrositeBaseUrl := "circe",
+  micrositeDocumentationUrl := "api",
+  micrositeGithubOwner := "travisbrown",
+  micrositeGithubRepo := "circe",
+  micrositeExtraMdFiles := Map(file("CONTRIBUTING.md") -> "contributing.md"),
+  micrositePalette := Map(
+    "brand-primary" -> "#5B5988",
+    "brand-secondary" -> "#292E53",
+    "brand-tertiary" -> "#222749",
+    "gray-dark" -> "#49494B",
+    "gray" -> "#7B7B7E",
+    "gray-light" -> "#E5E5E6",
+    "gray-lighter" -> "#F4F3F4",
+    "white-color" -> "#FFFFFF"),
+  addMappingsToSiteDir(mappings in (ScalaUnidoc, packageDoc), micrositeDocumentationUrl),
   ghpagesNoJekyll := false,
   scalacOptions in (ScalaUnidoc, unidoc) ++= Seq(
     "-groups",
@@ -125,6 +138,7 @@ lazy val docs = project.dependsOn(core, generic, parser, optics)
   .settings(
     addCompilerPlugin("org.scalamacros" % "paradise" % "2.1.0" cross CrossVersion.full)
   )
+  .enablePlugins(MicrositesPlugin)
 
 lazy val aggregatedProjects: Seq[ProjectReference] = Seq[ProjectReference](
   numbers, numbersJS,

docs/src/main/resources/microsite/data/menu.yml

@@ -0,0 +1,19 @@
+options:
+
+  - title: Parsing JSON
+    url: parsing.html
+
+  - title: Traversing and modifying JSON
+    url: cursors.html
+
+  - title: Encoding and decoding
+    url: codec.html
+
+  - title: Optics
+    url: optics.html
+
+  - title: Performance
+    url: performance.html
+
+  - title: Guide for contributors
+    url: contributing.html

docs/src/main/tut/codec.md

@@ -1,7 +1,7 @@
 ---
-layout: default
+layout: docs
 title:  "Encoding and decoding"
-section: "codec"
+position: 3
 ---
 
 # Encoding and decoding
@@ -38,7 +38,7 @@ decode[List[Int]]("[1, 2, 3]")
 
 ## Semi-automatic derivation
 
-Sometimes it's convenient to have an `Encoder` or `Decoder` defined in your code, and semi-automatic 
+Sometimes it's convenient to have an `Encoder` or `Decoder` defined in your code, and semi-automatic
 derivation can help. You'd write:
 
 ```tut:silent
@@ -76,7 +76,7 @@ NOTE: You will need the [Macro Paradise](http://docs.scala-lang.org/overviews/ma
 
 ### forProductN helper methods
 
-It's also possible to construct encoders and decoders for case class-like types 
+It's also possible to construct encoders and decoders for case class-like types
 in a relatively boilerplate-free way without generic derivation:
 
 ```tut:silent
@@ -147,7 +147,7 @@ implicit val decodeInstant: Decoder[Instant] = Decoder.decodeString.emap { str =
 
 ## Custom key types
 
-If you need to encode/decode `Map[K, V]` where `K` is not `String` (or `Symbol`, `Int`, `Long`, etc.), 
+If you need to encode/decode `Map[K, V]` where `K` is not `String` (or `Symbol`, `Int`, `Long`, etc.),
 you need to provide a `KeyEncoder` and/or `KeyDecoder` for your custom key type.
 
 For example:
@@ -177,7 +177,7 @@ json.as[Map[Foo, Int]]
 ## Warnings and known issues
 
 1. Please note that generic derivation will not work on Scala 2.10 unless you've added the [Macro
-   Paradise][paradise] plugin to your build. See the [quick start section on the home page]({{ site.baseurl }}/index.html#quick-start) 
+   Paradise][paradise] plugin to your build. See the [quick start section on the home page]({{ site.baseurl }}/index.html#quick-start)
    for details.
 
 2. Generic derivation may not work as expected when the type definitions that you're trying to

docs/src/main/tut/contributing.md

@@ -0,0 +1,93 @@
+---
+layout: docs
+title:  "Guide for contributors"
+position: 6
+---
+
+# Guide for contributors
+
+This project follows a standard [fork and pull][fork-and-pull] model for accepting contributions via
+GitHub pull requests:
+
+0. [Pick (or report) an issue](#pick-or-report-an-issue)
+1. [Write code](#write-code)
+2. [Write tests](#write-tests)
+3. [Submit a pull request](#submit-a-pull-request)
+
+## Pick or report an issue
+
+The [_beginner-friendly_][beginner-friendly] label flags [open issues][issues] where there is
+general agreement about the best way forward, and where the fix is likely to be relatively
+straightforward for someone with Scala experience. The [_help wanted_][help-wanted] label is a
+little more general, and indicates issues that may be much more challenging or have unresolved
+questions that need additional discussion.
+
+When you begin working on an issue, please leave a comment to notify others that the issue is taken,
+and join us in the [Gitter channel][gitter] if you have any questions along the way.
+
+We always welcome bug reports and feature requests—please don't feel like you need to have time to
+contribute a fix or implementation for your issue to be appreciated.
+
+## Write code
+
+The [design principles document](DESIGN.md) outlines some of the practices followed in the circe
+codebase. In general the public API should be purely functional, but the implementation is free to
+use non-functional constructions for the sake of performance—we want correctness, of course, but
+internally we're willing to have this correctness verified by tests rather than the compiler when
+necessary. That said, performance-motivated optimizations should be based on evidence, not
+speculation, and a functional style should be preferred whenever possible. When in doubt, get in
+touch on Gitter or look around the codebase to see how things are done.
+
+circe uses a fairly standard Scalastyle configuration to check formatting, and it may be useful to
+make your IDE aware of the following rules:
+
+* Code and comments should be formatted to a width no greater than 100 columns.
+* Files should not contain trailing spaces.
+* Imports should be sorted alphabetically.
+
+When in doubt, please run `sbt scalastyle` and let us know if you have any questions.
+
+## Write tests
+
+circe uses three testing libraries: [Discipline][discipline], [ScalaCheck][scalacheck], and
+[ScalaTest][scalatest], and organizes tests according to the following guidelines:
+
+* In general tests live in the `tests` sub-project. This allows e.g. tests for codecs in the core
+  module to be able to use the Jawn parser without circular dependencies between sub-projects.
+* For experimental or stand-alone modules, it may be appropriate for tests to live in the project.
+* Most test suites should extend `io.circe.tests.CirceSuite`, which provides many useful type class
+  instances and other tools.
+* Write tests that verify laws using Discipline whenever you can, then property-based tests using
+  ScalaCheck, then behavior-driven tests.
+* An assertion in regular tests should be written with `assert` and `===` (which in the context of
+  `CirceSuite` is Cats's type-safe equality operator, not the operator provided by ScalaTest).
+* An assertion in properties (inside `check`) should be written with `===`.
+
+You can run `sbt +validateJVM` to run Scalastyle checking and the JVM tests. `sbt +test` will run
+all tests, but requires _a lot_ of time and memory. Unless your contribution directly touches
+Scala.js-related code, it's generally not necessary to run the Scala.js tests—we'll verify
+compatibility before the next release.
+
+## Submit a pull request
+
+* Pull requests should be submitted from a separate branch (e.g. using
+  `git checkout -b "username/fix-123"`).
+* In general we discourage force pushing to an active pull-request branch that other people are
+  commenting on or contributing to, and suggest using `git merge master` during development. Once
+  development is complete, use `git rebase master` and force push to [clean up the history][squash].
+* The first line of a commit message should be no more than 72 characters long (to accommodate
+  formatting in various environments).
+* Commit messages should general use the present tense, normal sentence capitalization, and no final
+  punctuation.
+* If a pull request decreases code coverage more than by 2%, please file an issue to make sure that
+  tests get added.
+
+[beginner-friendly]: https://github.com/travisbrown/circe/labels/beginner-friendly
+[discipline]: https://github.com/typelevel/discipline
+[gitter]: https://gitter.im/travisbrown/circe
+[fork-and-pull]: https://help.github.com/articles/using-pull-requests/
+[help-wanted]: https://github.com/travisbrown/circe/labels/help%20wanted
+[issues]: https://github.com/travisbrown/circe/issues
+[scalacheck]: https://www.scalacheck.org/
+[scalatest]: http://www.scalatest.org/
+[squash]: http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html

docs/src/main/tut/cursors.md

@@ -1,7 +1,7 @@
 ---
-layout: default
+layout: docs
 title:  "Traversing and modifying JSON"
-section: "cursors"
+position: 2
 ---
 
 # Traversing and modifying JSON
@@ -57,7 +57,7 @@ val secondQux: Decoder.Result[String] =
 
 ## Transforming data
 
-We can also use a cursor to modify JSON. 
+We can also use a cursor to modify JSON.
 
 ```tut:silent
 val reversedNameCursor: ACursor =

docs/src/site/index.md → docs/src/main/tut/index.md

@@ -1,5 +1,5 @@
 ---
-layout: default
+layout: home
 title:  "Home"
 section: "home"
 ---
@@ -12,12 +12,12 @@ section: "home"
 circe (pronounced SUR-see, or KEER-kee in classical Greek, or CHEER-chay in Ecclesiastical Latin) is
 a JSON library for Scala (and [Scala.js][scala-js]).
 
-circe's working title was jfc, which stood for "JSON for [cats][cats]". The name was changed for 
+circe's working title was jfc, which stood for "JSON for [cats][cats]". The name was changed for
 [a number of reasons](https://github.com/travisbrown/circe/issues/11).
 
 <a name="quick-start"></a>
 
-{% include_relative _tut/quickstart.md %}
+{% include_relative quickstart.md %}
 
 ## Why?
 
@@ -48,15 +48,15 @@ fussiest code in Argonaut. The [`jackson`][circe-jackson] subproject supports us
 circe also provides a [`parser`][circe-parser] subproject that provides parsing support for Scala.js,
 with JVM parsing provided by `io.circe.jawn` and JavaScript parsing from `scalajs.js.JSON`.
 
-See the [Parsing page](tut/parsing.html) for more details.
+See the [Parsing page](parsing.html) for more details.
 
 ### Lenses
 
 circe doesn't use or provide lenses in the `core` project. This is related to the first point above,
 since [Monocle][monocle] has a Scalaz dependency, but we also feel that it simplifies the API. The
 0.3.0 release added [an experimental `optics` subproject][optics-pr] that provides Monocle lenses.
 
-See the [Optics page](tut/optics.html) for more details.
+See the [Optics page](optics.html) for more details.
 
 ### Codec derivation
 
@@ -70,7 +70,7 @@ example), circe includes a subproject (`generic`) that provides generic codec de
 case classes and sealed trait hierarchies. It also includes derivation of "incomplete" case class
 instances (see my recent [blog post][incompletes] for details).
 
-See the [Encoding and Decoding page](tut/codec.html) for more details.
+See the [Encoding and Decoding page](codec.html) for more details.
 
 ### Aliases
 

docs/src/main/tut/optics.md

@@ -1,12 +1,12 @@
 ---
-layout: default
+layout: docs
 title:  "Optics"
-section: "optics"
+position: 4
 ---
 
 # Optics
 
-Optics are a powerful tool for traversing and modifying JSON documents. They can reduce boilerplate 
+Optics are a powerful tool for traversing and modifying JSON documents. They can reduce boilerplate
 considerably, especially if you are working with deeply nested JSON.
 
 circe provides support for optics by integrating with [Monocle](monocle). To use them, add a
@@ -72,8 +72,8 @@ val _phoneNum = root.order.customer.contactDetails.phone.string
 val phoneNum: Option[String] = _phoneNum.getOption(json)
 ```
 
-Note the difference between cursors and optics. With cursors, we start with a JSON document, get a 
-cursor from it, and then use that cursor to traverse the document. With optics, on the other hand, 
+Note the difference between cursors and optics. With cursors, we start with a JSON document, get a
+cursor from it, and then use that cursor to traverse the document. With optics, on the other hand,
 we first define the traversal we want to make, then apply it to a JSON document.
 
 In other words, optics provide a way to separate the description of a JSON traversal from its
@@ -98,7 +98,7 @@ val quantities: Seq[Int] =
 And with optics:
 
 ```tut:book
-val items: Seq[Int] = 
+val items: Seq[Int] =
   root.order.items.each.quantity.int.getAll(json)
 ```
 
@@ -110,9 +110,9 @@ Suppose we decide to have a 2-for-1 sale, so we want to double all the quantitie
 can be achieved with a small change to the code we wrote for traversal:
 
 ```tut:book
-val doubleQuantities: Json => Json = 
+val doubleQuantities: Json => Json =
   root.order.items.each.quantity.int.modify(_ * 2)
- 
+
 val modifiedJson = doubleQuantities(json)
 ```
 

docs/src/main/tut/parsing.md

@@ -1,7 +1,7 @@
 ---
-layout: default
+layout: docs
 title:  "Parsing JSON"
-section: "parsing"
+position: 1
 ---
 
 # Parsing JSON

docs/src/site/performance.md → docs/src/main/tut/performance.md

@@ -1,7 +1,7 @@
 ---
-layout: default
+layout: docs
 title:  "Performance"
-section: "performance"
+position: 5
 ---
 
 # Performance