WIP

build.sbt

@@ -146,12 +146,13 @@ lazy val readme = (project in file("modules/readme"))
 
 lazy val docs = (project in file("docs"))
   .dependsOn(coreJVM)
+  .dependsOn(macrosJVM)
   .dependsOn(athemaJVM)
   .settings(moduleName := "droste-docs")
   .settings(micrositeSettings: _*)
   .settings(noPublishSettings: _*)
+  .settings(libraryDependencies ++= paradiseDep(scalaVersion.value))
+  .settings(micrositeCompilingDocsTool := WithMdoc)
   .enablePlugins(MicrositesPlugin)
   .disablePlugins(ProjectPlugin)
-  .settings(
-    scalacOptions in Tut ~= (_ filterNot Set("-Ywarn-unused-import", "-Xlint").contains)
-  )
+  .settings(mdocIn := tutSourceDirectory.value)

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

@@ -4,3 +4,12 @@ options:
 
   - title: Typeclasses
     url: docs/core/typeclasses
+
+  - title: Fixpoint types
+    url: docs/core/fixpoint-types
+
+  - title: Recursion schemes
+    url: docs/core/recursion-schemes
+
+  - title: Annotations
+    url: docs/core/annotations

docs/src/main/tut/docs/core/annotations/README.md

@@ -0,0 +1,80 @@
+---
+layout: docs
+title: annotations
+permalink: /docs/core/annotations/
+---
+
+# annotations
+
+Droste provides a couple of very useful annotations in the
+`droste-macros` module.
+
+## @deriveFixedPoint
+
+`@deriveFixedPoint` can be used in a plain old recursive ADT to
+generate the non-recursive counterpart.
+
+There are some restrictions in order to use `@deriveFixedPoint`:
+- the annotee should be either a `sealed trait` or `sealed abstract class`
+- cases of the ADT should be declared inside the companion object
+- recursion should appear on positive postion, somethink like follows will not compile:
+
+``` scala mdoc:fail
+import higherkindness.droste.macros.deriveFixedPoint
+
+@deriveFixedPoint sealed trait X
+object X{
+  // here, X appears in negative postition
+  case class Y[A](f: X => Int) extends X 
+}
+```
+
+
+This annotation will create a `object fixedpoint` within the companion
+object of the annotated `sealed trait` or `sealed abstract class` with
+the following:
+
+- Generate the non-recursive ADT
+- create a `Traverse` instance for it
+- create a Recursive => NonRecursive[A] coalgebra
+- create a NonRecursive[A] => Recursive algebra
+- create a `Basis` instance
+
+``` scala mdoc
+import cats.instances.list._
+
+import higherkindness.droste.Basis
+import higherkindness.droste.syntax.all._
+import higherkindness.droste.macros.deriveFixedPoint
+
+@deriveFixedPoint sealed trait Expr
+object Expr {
+  case class Val(i: Int) extends Expr
+  case class Sum(a: Expr, b: Expr) extends Expr
+
+  def `val`[A](i: Int): fixedpoint.ExprF[A]  = fixedpoint.ValF(i)
+  def sum[A](a: A, b: A): fixedpoint.ExprF[A] = fixedpoint.SumF(a, b)
+}
+
+import Expr._
+import Expr.fixedpoint._
+
+def program[T: Basis[ExprF, ?]]: T = 
+  sum[T](
+    sum[T](
+	  `val`[T](1).embed,
+	  `val`[T](2).embed
+	).embed,
+    sum[T](
+	  `val`[T](3).embed,
+	  `val`[T](4).embed
+	).embed
+  ).embed
+
+val numbersToBeAdded = program[Expr].collect[List[Int], Int] {
+  case Val(x) => x
+}
+
+println(numbersToBeAdded)
+```
+

docs/src/main/tut/docs/core/fixpoint-types/README.md

@@ -10,7 +10,7 @@ The basic idea of recursion schemes is that we factor the recursion
 out of recursive data types.  We do so by converting recursive data
 types:
 
-``` scala
+``` scala mdoc
 sealed trait Expr
 case class Sum(a: Expr, b: Expr) extends Expr
 case class Val(a: Int) extends Expr
@@ -19,7 +19,7 @@ case class Val(a: Int) extends Expr
 into non-recursive data types, in which the recursion is factored to a
 type parameter.
 
-``` scala
+``` scala mdoc
 sealed trait ExprF[A]
 case class SumF[A](a: A, b: A) extends ExprF[A]
 case class ValF[A](a: Int) extends ExprF[A]
@@ -32,25 +32,25 @@ However, how do we create values using our new ADT?  Imagine we want
 to represent the `1 + 2` expression.  In the first version of
 `Expr`, it's easy:
 
-``` scala
+``` scala mdoc
 val sum: Expr = Sum(Val(1), Val(2))
 ```
 
 However, using the second type is not as easy, if we try to follow the
 same approach, we see that something doesn't work:
 
-``` scala
-val sumF: ??? = SumF(ValF(1), ValF(2))
+``` scala mdoc
+val sumF: ExprF[ExprF[Int]] = SumF(ValF(1), ValF(2))
 ```
 
 What's the type of `sumF` now? If we'd start substituting we'd get
-something like `Expr[Expr[...]]`, and that's not what we want.
+something like `ExprF[ExprF[...]]`, and that's not what we want.
 
 Introducing fixpoint types.
 
 Fixpoint types are the missing piece in the previous approach to
-datatypes.  They allow us to represent recursion, there are several of
-them, but we will focus on `Fix` now.
+datatypes, they tie the recursive knot in order to avoid scenarios
+such as `ExprF[ExprF[ExprF[...]]]`.
 
 ## Fix
 
@@ -91,7 +91,9 @@ very useful when you need to add an annotation, or attribute, to the
 values in your pattern functor.
 
 `Attr` can be used for:
-* doing [type inference](https://brianmckenna.org/blog/type_annotation_cofree) in an AST, in which the annotation would be the
-  type.
+* [annotating an AST with types](https://brianmckenna.org/blog/type_annotation_cofree)
 * [annotating an AST with positions in the source file](https://github.com/haskell-nix/hnix/blob/master/src/Nix/Expr/Types/Annotated.hs).
 
+# Pattern Functors
+
+Pattern functors are the 

docs/src/main/tut/docs/core/recursion-schemes/README.md

@@ -6,11 +6,38 @@ permalink: /docs/core/recursion-schemes/
 
 # Recursion Schemes
 
-## Folds
+## Basics
 
-Folds ha
+### Folds
 
-## Unfods
+Folds are used to consume data structures
 
-## gather / scatter
+### Unfolds
+
+Unfolds are used to produce data structures
+
+### Refolds
+
+Refolds go one way and then the other.
+
+## monadic recursion schemes
+
+Monadic recursion schemes are monadic version of already known
+recursion schemes.  With monadic version we refer to recursion schemes
+in which the return values is wrapped inside a monad:
 
+```scala
+def cataM[M[_]: Monad, F[_]: Traverse, R, B](
+  algebraM: AlgebraM[M, F, B]
+)(implicit project: Project[F, R]): R => M[B]
+```
+
+They are marked with an `M` suffix in their name,
+and the big difference is that they require a `Traverse` instance in
+the pattern functor.  Some examples are `cataM`, `anaM`, or `histoM`.
+
+Monadic recursion schemes are useful when we need to 
+
+## Generalized
+
+## gather / scatter

docs/src/main/tut/docs/core/typeclasses/README.md

@@ -7,12 +7,12 @@ permalink: /docs/core/typeclasses/
 # Type Classes
 
 There are two main typeclasses in droste, `Project[F[_]]` and
-`Embed[F[_]]` respectively.
+`Embed[F[_]]` .
 
 
 ## Embed
 
-All fixpoint types that allow _lifting_ a pattern functor inside them
+All [fixpoint types](/docs/core/fixpoint-types/) that allow _lifting_ a pattern functor inside them
 have an instance of `Embed`.  `Embed` is declared as follows:
 
 ``` scala
@@ -23,7 +23,7 @@ trait Embed[F[_], R] {
 
 ## Project
 
-All fixpoint types from which we can extract a pattern functor have
+All [fixpoint types](/docs/core/fixpoint-types) from which we can extract a pattern functor have
 instances for `Project`.  Project is declared as follows:
 
 ``` scala
@@ -32,29 +32,6 @@ trait Project[F[_], R] {
 }
 ```
 
-One cool feature of `Project` is that it provides `Foldable` operators
-if the `F[_]` is a `Foldable` too!
-
-``` tut:silent
-import qq.droste.macros.deriveTraverse
-
-@deriveTraverse sealed trait Lambda[A]
-object Lambda {
-  case class Var[A](name: String) extends Lambda[A]
-  case class App[A](f: A, p: A) extends Lambda[A]
-  case class Lam[A](name: String, body: A) extends Lambda[A]
-}
-
-import qq.droste.syntax.project._
-
-val list: Fix[Lambda] = Fix(App(Fix("a"), Fix(Var("b"))))
-
-val allVars: List[String] = list collect {
-  case Var(n) => n
-}
-```
-
-
 ## Basis
 
 Basis is a typeclass for types that are both an `Embed` and `Project`.

project/plugins.sbt

@@ -6,4 +6,4 @@ addSbtPlugin("org.scoverage"      % "sbt-scoverage"                 % "1.6.0-M5"
 addSbtPlugin("io.get-coursier"    % "sbt-coursier"                  % "1.1.0-M5")
 addSbtPlugin("io.crashbox"        % "sbt-gpg"                       % "0.1.6")
 addSbtPlugin("com.github.gseitz"  % "sbt-release"                   % "1.0.9")
-addSbtPlugin("com.47deg"          % "sbt-microsites"                % "0.7.23")
+addSbtPlugin("com.47deg"          % "sbt-microsites"                % "0.9.1")