WIP: added documentation for circe-derivation

build.sbt

@@ -182,7 +182,8 @@ lazy val docs = project
     mdocIn := file("docs/src/main/tut"),
     libraryDependencies ++= Seq(
       "io.circe" %% "circe-generic-extras" % "0.12.2",
-      "io.circe" %% "circe-optics" % "0.12.0"
+      "io.circe" %% "circe-optics" % "0.12.0",
+      "io.circe" %% "circe-derivation" % "0.13.0-SNAPSHOT"
     )
   )
   .settings(docSettings)

docs/src/main/tut/codecs/semiauto-derivation.md

@@ -64,3 +64,43 @@ implicit val encodeUser: Encoder[User] =
 ```
 
 It's not as clean or as maintainable as generic derivation, but it's less magical, it requires nothing but `circe-core`, and if you need a custom name mapping it's currently the best solution (although `0.6.0` introduces experimental configurable generic derivation in the `circe-generic-extras` module).
+
+### circe-derivation (macro based)
+
+Using a companion library [circe-derivation](https://github.com/circe/circe-derivation) it is easy to define semi automatic derivation with fast compile times.
+
+```scala mdoc:silent:reset
+import io.circe._, io.circe.derivation._
+
+case class Foo(a: Int, b: String, c: Boolean)
+
+implicit val fooDecoder: Decoder[Foo] = deriveDecoder
+implicit val fooEncoder: Encoder[Foo] = deriveEncoder
+```
+
+`deriveDecoder` supports renaming, opting for using case class defaults and providing a custom discriminator, similarly `deriveEncoder` supports renaming and custom discriminator.
+Thus can be used for a drop-in replacement for `io.circe.generic.semiauto`
+
+```scala mdoc:silent:reset
+import io.circe._, io.circe.derivation._
+
+case class User(id: Long, firstName: String, lastName: String)
+
+implicit val decodeUser: Decoder[User] = deriveDecoder(renaming.snakeCase)
+implicit val encodeUser: Encoder[User] = deriveEncoder(renaming.snakeCase)
+```
+
+alternatively there is also `deriveCodec`
+
+```scala mdoc:silent:reset
+import io.circe._, io.circe.derivation._
+
+case class User(id: Long, firstName: String, lastName: String)
+
+val userCodec: Codec[User] = deriveCodec(renaming.snakeCase)
+```
+
+NOTE: `deriveDecoder`, `deriveEncoder` and `deriveCodec` all have default arguments. They can either be supplied no arguments, only renaming or all arguments.
+The default value for `useDefaults` is `true` in case of `circe-derivation`, which is different from default behaviour of `io.circe.generic.semiauto`.
+
+More information on `circe-derivation` is available in its [readme](https://github.com/circe/circe-derivation/blob/master/README.md)