Add tut contrib module (#464)

* Add tut contrib module

* Add TutModule tests and documentation

* Use Path instead of PathRef for tut target directory

* Use the correct scala version in TutModule

* Ensure resolving tut doesn't bring in extra scala-library jars

* Ensure MILL_VERSION system property is set in tut tests

* Fork to run tut to fix classpath problems, add test with library usage

* Follow convention w.r.t. publishVersion in testArgs

* Add Scaladoc to TutModule

* Don't supply a default version of Tut

* Update docs to account for mandatory tutVersion setting

* Inline tutArgs, otherwise Tut does not recompile when sources change

3 files changed, 137 insertions, 0 deletions

diff --git a/contrib/tut/test/src/mill/contrib/tut/TutTests.scala b/contrib/tut/test/src/mill/contrib/tut/TutTests.scala
new file mode 100644
index 00000000..fd369eed
--- /dev/null
+++ b/contrib/tut/test/src/mill/contrib/tut/TutTests.scala
@@ -0,0 +1,124 @@
+package mill.contrib
+package tut
+
+import ammonite.ops._
+import mill._
+import mill.eval.Result._
+import mill.scalalib._
+import mill.util.{TestEvaluator, TestUtil}
+import utest._
+import utest.framework.TestPath
+
+object TutTests extends TestSuite {
+
+  trait TutTestModule extends TestUtil.BaseModule with TutModule {
+    def millSourcePath = TestUtil.getSrcPathBase() / millOuterCtx.enclosing.split('.')
+    def scalaVersion = "2.12.4"
+    def tutVersion = "0.6.7"
+  }
+
+  object TutTest extends TutTestModule
+
+  object TutCustomTest extends TutTestModule {
+    def tutTargetDirectory = millSourcePath
+  }
+
+  object TutLibrariesTest extends TutTestModule {
+    def ivyDeps = Agg(ivy"org.typelevel::cats-core:1.4.0")
+    def tutSourceDirectory = T.sources { resourcePathWithLibraries }
+    def scalacPluginIvyDeps = Agg(ivy"org.spire-math::kind-projector:0.9.8")
+  }
+
+  val resourcePath = pwd / 'contrib / 'tut / 'test / 'tut
+  val resourcePathWithLibraries = pwd / 'contrib / 'tut / 'test / "tut-with-libraries"
+
+  def workspaceTest[T](m: TestUtil.BaseModule, resourcePath: Path = resourcePath)
+                      (t: TestEvaluator => T)
+                      (implicit tp: TestPath): T = {
+    val eval = new TestEvaluator(m)
+    rm(m.millSourcePath)
+    rm(eval.outPath)
+    mkdir(m.millSourcePath)
+    cp(resourcePath, m.millSourcePath / 'tut)
+    t(eval)
+  }
+
+  def tests: Tests = Tests {
+    'tut - {
+      'createOutputFile - workspaceTest(TutTest) { eval =>
+        val expectedPath =
+          eval.outPath / 'tutTargetDirectory / 'dest / "TutExample.md"
+
+        val expected =
+          """
+          |```scala
+          |scala> 1 + 1
+          |res0: Int = 2
+          |```
+          |
+          """.trim.stripMargin
+
+        val Right((result, evalCount)) = eval.apply(TutTest.tut)
+
+        assert(
+          exists(expectedPath) &&
+            read! expectedPath == expected
+        )
+      }
+
+      'supportCustomSettings - workspaceTest(TutCustomTest) { eval =>
+        val defaultPath =
+          eval.outPath / 'tutTargetDirectory / 'dest / "TutExample.md"
+        val expectedPath =
+          TutCustomTest.millSourcePath / "TutExample.md"
+
+        val expected =
+          """
+          |```scala
+          |scala> 1 + 1
+          |res0: Int = 2
+          |```
+          |
+          """.trim.stripMargin
+
+        val Right((result, evalCount)) = eval.apply(TutCustomTest.tut)
+
+        assert(
+          !exists(defaultPath) &&
+            exists(expectedPath) &&
+            read! expectedPath == expected
+        )
+      }
+
+      'supportUsingLibraries - workspaceTest(TutLibrariesTest, resourcePath = resourcePathWithLibraries) { eval =>
+        val expectedPath =
+          eval.outPath / 'tutTargetDirectory / 'dest / "TutWithLibraries.md"
+
+        val expected =
+          """
+            |```scala
+            |import cats._
+            |import cats.arrow.FunctionK
+            |import cats.implicits._
+            |```
+            |
+            |```scala
+            |scala> List(1, 2, 3).combineAll
+            |res0: Int = 6
+            |
+            |scala> λ[FunctionK[List, Option]](_.headOption)(List(1, 2 ,3))
+            |res1: Option[Int] = Some(1)
+            |```
+            |
+          """.trim.stripMargin
+
+        val Right(_) = eval.apply(TutLibrariesTest.tut)
+
+        assert(
+          exists(expectedPath) &&
+            read! expectedPath == expected
+        )
+      }
+    }
+  }
+}
diff --git a/contrib/tut/test/tut-with-libraries/TutWithLibraries.md b/contrib/tut/test/tut-with-libraries/TutWithLibraries.md
new file mode 100644
index 00000000..7df1e703
--- /dev/null
+++ b/contrib/tut/test/tut-with-libraries/TutWithLibraries.md
@@ -0,0 +1,10 @@
+```tut:silent
+import cats._
+import cats.arrow.FunctionK
+import cats.implicits._
+```
+
+```tut
+List(1, 2, 3).combineAll
+λ[FunctionK[List, Option]](_.headOption)(List(1, 2 ,3))
+```
diff --git a/contrib/tut/test/tut/TutExample.md b/contrib/tut/test/tut/TutExample.md
new file mode 100644
index 00000000..c149fbc6
--- /dev/null
+++ b/contrib/tut/test/tut/TutExample.md
@@ -0,0 +1,3 @@
+```tut
+1 + 1
+```