Bare minimum docs

.scalafmt.conf

@@ -1,3 +1,4 @@
+version = "2.6.4"
 style = defaultWithAlign
 maxColumn = 80
 

README.md

@@ -42,20 +42,16 @@ val fib: BigDecimal => BigDecimal = scheme.ghylo(
 ```
 
 ```scala
-scala> fib(0)
-res0: BigDecimal = 0
-
-scala> fib(1)
-res1: BigDecimal = 1
-
-scala> fib(2)
-res2: BigDecimal = 1
-
-scala> fib(10)
-res3: BigDecimal = 55
-
-scala> fib(100)
-res4: BigDecimal = 354224848179261915075
+fib(0)
+// res0: BigDecimal = 0
+fib(1)
+// res1: BigDecimal = 1
+fib(2)
+// res2: BigDecimal = 1
+fib(10)
+// res3: BigDecimal = 55
+fib(100)
+// res4: BigDecimal = 354224848179261915075
 ```
 
 An anamorphism followed by a histomorphism is also known as a
@@ -69,20 +65,16 @@ val fibAlt: BigDecimal => BigDecimal =
 ```
 
 ```scala
-scala> fibAlt(0)
-res5: BigDecimal = 0
-
-scala> fibAlt(1)
-res6: BigDecimal = 1
-
-scala> fibAlt(2)
-res7: BigDecimal = 1
-
-scala> fibAlt(10)
-res8: BigDecimal = 55
-
-scala> fibAlt(100)
-res9: BigDecimal = 354224848179261915075
+fibAlt(0)
+// res5: BigDecimal = 0
+fibAlt(1)
+// res6: BigDecimal = 1
+fibAlt(2)
+// res7: BigDecimal = 1
+fibAlt(10)
+// res8: BigDecimal = 55
+fibAlt(100)
+// res9: BigDecimal = 354224848179261915075
 ```
 
 What if we want to do two things at once? Let's calculate a
@@ -106,20 +98,16 @@ val sumSquares: BigDecimal => BigDecimal = scheme.ghylo(
 ```
 
 ```scala
-scala> sumSquares(0)
-res11: BigDecimal = 0
-
-scala> sumSquares(1)
-res12: BigDecimal = 1
-
-scala> sumSquares(2)
-res13: BigDecimal = 5
-
-scala> sumSquares(10)
-res14: BigDecimal = 385
-
-scala> sumSquares(100)
-res15: BigDecimal = 338350
+sumSquares(0)
+// res10: BigDecimal = 0
+sumSquares(1)
+// res11: BigDecimal = 1
+sumSquares(2)
+// res12: BigDecimal = 5
+sumSquares(10)
+// res13: BigDecimal = 385
+sumSquares(100)
+// res14: BigDecimal = 338350
 ```
 
 Now we can zip the two algebras into one so that we calculate
@@ -134,20 +122,16 @@ val fused: BigDecimal => (BigDecimal, BigDecimal) =
 ```
 
 ```scala
-scala> fused(0)
-res16: (BigDecimal, BigDecimal) = (0,0)
-
-scala> fused(1)
-res17: (BigDecimal, BigDecimal) = (1,1)
-
-scala> fused(2)
-res18: (BigDecimal, BigDecimal) = (1,5)
-
-scala> fused(10)
-res19: (BigDecimal, BigDecimal) = (55,385)
-
-scala> fused(100)
-res20: (BigDecimal, BigDecimal) = (354224848179261915075,338350)
+fused(0)
+// res15: (BigDecimal, BigDecimal) = (0, 0)
+fused(1)
+// res16: (BigDecimal, BigDecimal) = (1, 1)
+fused(2)
+// res17: (BigDecimal, BigDecimal) = (1, 5)
+fused(10)
+// res18: (BigDecimal, BigDecimal) = (55, 385)
+fused(100)
+// res19: (BigDecimal, BigDecimal) = (354224848179261915075, 338350)
 ```
 
 Droste includes [athema](athema), a math expression parser/processor,

build.sbt

@@ -170,35 +170,35 @@ lazy val athemaJVM = athema.jvm
 lazy val athemaJS  = athema.js
 
 lazy val readme = (project in file("modules/readme"))
-  .enablePlugins(TutPlugin)
+  .enablePlugins(MdocPlugin)
   .dependsOn(coreJVM)
   .dependsOn(athemaJVM)
   .settings(noPublishSettings)
   .disablePlugins(MimaPlugin)
   .settings(
-    scalacOptions in Tut ~= {
-      _.filterNot(
-        Set("-Ywarn-unused-import", "-Yno-predef", "-Ywarn-unused:imports"))
-    },
-    tutTargetDirectory := (baseDirectory in LocalRootProject).value
+    mdocExtraArguments := Seq(
+      "--in", baseDirectory.value + "/src/main/tut/README.md",
+      "--out", (baseDirectory in LocalRootProject).value + "/README.md"
+    )
   )
 
 ///////////////
 //// DOCS ////
 ///////////////
 
-lazy val docs = (project in file("docs"))
+lazy val docs = (project in file("microsite"))
   .dependsOn(coreJVM)
+  .dependsOn(macrosJVM)
   .dependsOn(athemaJVM)
-  .settings(moduleName := "droste-docs")
+  .settings(moduleName := "droste-microsite")
   .settings(micrositeSettings: _*)
   .settings(noPublishSettings: _*)
+  .settings(libraryDependencies ++= paradiseDep(scalaVersion.value))
+  .settings(micrositeCompilingDocsTool := WithMdoc)
   .enablePlugins(MicrositesPlugin)
   .disablePlugins(ProjectPlugin)
   .disablePlugins(MimaPlugin)
-  .settings(
-    scalacOptions in Tut ~= (_ filterNot Set("-Ywarn-unused-import", "-Xlint").contains)
-  )
+  .settings(mdocIn := tutSourceDirectory.value)
 
 //////////////////
 //// ALIASES /////
@@ -208,4 +208,4 @@ addCommandAlias(
   "ci-test",
   ";+clean;+test"
 )
-addCommandAlias("ci-docs", ";readme/tut")
+addCommandAlias("ci-docs", "github; docs/mdoc; readme/mdoc")

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

@@ -1,3 +1,15 @@
 options:
   - title: Quick Start
-    url: docs/
+    url: docs/
+
+  - 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/README.md

@@ -6,6 +6,6 @@ permalink: /docs/core/
 
 # Core
 
-* [Data Structures](dataStructures/)
-* [Type Classes](typeClasses/)
-* [Recursion Schemes](recursionSchemes/)
+* [Fixpoint types](fixpoint-types/)
+* [Typeclasses](typeclasses/)
+* [Recursion Schemes](recursion-schemes/)

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

@@ -0,0 +1,79 @@
+---
+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

@@ -0,0 +1,99 @@
+---
+layout: docs
+title: fixpoint types
+permalink: /docs/core/fixpoint-types/
+---
+
+# Fixpoint types
+
+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 mdoc
+sealed trait Expr
+case class Sum(a: Expr, b: Expr) extends Expr
+case class Val(a: Int) extends Expr
+```
+
+into non-recursive data types, in which the recursion is factored to a
+type parameter.
+
+```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]
+```
+
+As you can see, we replace occurences of explicit recursion with the
+type parameter `A`.
+
+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 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 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 `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 tie the recursive knot in order to avoid scenarios
+such as `ExprF[ExprF[ExprF[...]]]`.
+
+## Fix
+
+Fix is the simplest of fixpoint data types, and it's declaration is as
+follows:
+
+```scala
+case class Fix[F[_]](unFix: F[Fix[F]])
+```
+
+Even though it may look extrange, the idea is quite simple.  Let's get
+back to the previous example.  Using `Fix` we can now define our value
+sumF as follows:
+
+```scala
+val sumF: Fix[ExprF] = Fix(SumF(Fix(ValF(1)), Fix(ValF(2))))
+```
+
+## Mu
+
+`Mu` is a fixpoint datatype that is declared as the fold (`cata`) of a
+datastructure.
+
+## Nu
+
+`Nu` is a fixpoint type declared as the unfold (`ana`) of a datastructure.
+
+## Coattr
+
+`Coattr`, also known as `Free`, is a fixpoint type in which the leaves
+of the tree are annotated with an additional value.
+
+## Attr
+
+`Attr`, also known as `Cofree`, is a fixpoint type in which al levels
+of the tree are annotated with an additional value.  Using `Attr` is
+very useful when you need to add an annotation, or attribute, to the
+values in your pattern functor.
+
+`Attr` can be used for:
+* [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