make tut doc ever so slightly less hideous

docs/src/main/tut/apply.md

@@ -14,8 +14,9 @@ a context can be `Option`, `List` or `Future` for example).
 However, the difference between `ap` and `map` is that for `ap` the function that 
 takes care of the transformation is of type `F[A => B]`, whereas for `map` it is `A => B`:
 
-```tut
+```tut:silent
 import cats._
+
 val intToString: Int => String = _.toString
 val double: Int => Int = _ * 2
 val addTwo: Int => Int = _ + 2
@@ -133,8 +134,6 @@ f2(Some(1), Some(2), Some(3))
 All instances created by `|@|` have `map`, `ap`, and `tupled` methods of the appropriate arity:
 
 ```tut
-import cats.syntax.apply._
-
 val option2 = Option(1) |@| Option(2)
 val option3 = option2 |@| Option.empty[Int]
 

docs/src/main/tut/const.md

@@ -13,13 +13,13 @@ have its uses, which serve as a nice example of the consistency and elegance of
 ## Thinking about `Const`
 The `Const` data type can be thought of similarly to the `const` function, but as a data type.
 
-```tut
+```tut:silent
 def const[A, B](a: A)(b: => B): A = a
 ```
 
 The `const` function takes two arguments and simply returns the first argument, ignoring the second.
 
-```scala
+```tut:silent
 final case class Const[A, B](getConst: A)
 ```
 
@@ -44,7 +44,7 @@ to use a lens.
 A lens can be thought of as a first class getter/setter. A `Lens[S, A]` is a data type that knows how to get
 an `A` out of an `S`, or set an `A` in an `S`.
 
-```tut
+```tut:silent
 trait Lens[S, A] {
   def get(s: S): A
 
@@ -58,7 +58,7 @@ trait Lens[S, A] {
 It can be useful to have effectful modifications as well - perhaps our modification can fail (`Option`) or
 can return several values (`List`).
 
-```tut
+```tut:silent
 trait Lens[S, A] {
   def get(s: S): A
 
@@ -78,7 +78,7 @@ trait Lens[S, A] {
 Note that both `modifyOption` and `modifyList` share the *exact* same implementation. If we look closely, the
 only thing we need is a `map` operation on the data type. Being good functional programmers, we abstract.
 
-```tut
+```tut:silent
 import cats.Functor
 import cats.syntax.functor._
 
@@ -99,7 +99,7 @@ We can redefine `modify` in terms of `modifyF` by using `cats.Id`. We can also t
 that simply ignores the current value. Due to these modifications however, we must leave `modifyF` abstract
 since having it defined in terms of `set` would lead to infinite circular calls.
 
-```tut
+```tut:silent
 import cats.Id
 
 trait Lens[S, A] {
@@ -134,7 +134,7 @@ is to take an `A` and return it right back (lifted into `Const`).
 Before we plug and play however, note that `modifyF` has a `Functor` constraint on `F[_]`. This means we need to
 define a `Functor` instance for `Const`, where the first type parameter is fixed.
 
-```tut
+```tut:silent
 import cats.data.Const
 
 implicit def constFunctor[X]: Functor[Const[X, ?]] =
@@ -147,7 +147,7 @@ implicit def constFunctor[X]: Functor[Const[X, ?]] =
 
 Now that that's taken care of, let's substitute and see what happens.
 
-```tut
+```tut:silent
 trait Lens[S, A] {
   def modifyF[F[_] : Functor](s: S)(f: A => F[A]): F[S]
 
@@ -174,7 +174,7 @@ In the popular [The Essence of the Iterator Pattern](https://www.cs.ox.ac.uk/jer
 paper, Jeremy Gibbons and Bruno C. d. S. Oliveria describe a functional approach to iterating over a collection of
 data. Among the abstractions presented are `Foldable` and `Traverse`, replicated below (also available in Cats).
 
-```tut
+```tut:silent
 import cats.{Applicative, Monoid}
 
 trait Foldable[F[_]] {
@@ -194,7 +194,7 @@ These two type classes seem unrelated - one reduces a collection down to a singl
 a collection with an effectful function, collecting results. It may be surprising to see that in fact `Traverse`
 subsumes `Foldable`.
 
-```tut
+```tut:silent
 trait Traverse[F[_]] extends Foldable[F] {
   def traverse[G[_] : Applicative, A, X](fa: F[A])(f: A => G[X]): G[F[X]]
 
@@ -211,7 +211,7 @@ However, if we imagine `G[_]` to be a sort of type-level constant function, wher
 `F[X]` is the value we want to ignore, we treat it as the second type parameter and hence, leave it as the free
 one.
 
-```tut
+```tut:silent
 import cats.data.Const
 
 implicit def constApplicative[Z]: Applicative[Const[Z, ?]] =
@@ -235,7 +235,7 @@ should try to do something more useful. This suggests composition of `Z`s, which
 So now we need a constant `Z` value, and a binary function that takes two `Z`s and produces a `Z`. Sound familiar?
 We want `Z` to have a `Monoid` instance!
 
-```tut
+```tut:silent
 implicit def constApplicative[Z : Monoid]: Applicative[Const[Z, ?]] =
   new Applicative[Const[Z, ?]] {
     def pure[A](a: A): Const[Z, A] = Const(Monoid[Z].empty)
@@ -261,7 +261,7 @@ So to summarize, what we want is a function `A => Const[B, Nothing]`, and we hav
 that `Const[B, Z]` (for any `Z`) is the moral equivalent of just `B`, so `A => Const[B, Nothing]` is equivalent
 to `A => B`, which is exactly what we have, we just need to wrap it.
 
-```tut
+```tut:silent
 trait Traverse[F[_]] extends Foldable[F] {
   def traverse[G[_] : Applicative, A, X](fa: F[A])(f: A => G[X]): G[F[X]]
 

docs/src/main/tut/foldable.md

@@ -23,10 +23,16 @@ used by the associated `Foldable[_]` instance.
 These form the basis for many other operations, see also: 
 [A tutorial on the universality and expressiveness of fold](https://www.cs.nott.ac.uk/~gmh/fold.pdf) 
 
-```tut
+First some standard imports.
+
+```tut:silent
 import cats._
 import cats.std.all._
+```
+
+And examples.
 
+```tut
 Foldable[List].fold(List("a", "b", "c"))
 Foldable[List].foldMap(List(1, 2, 4))(_.toString)
 Foldable[List].foldK(List(List(1,2,3), List(2,3,4)))
@@ -70,13 +76,13 @@ Hence when defining some new data structure, if we can define a `foldLeft` and
 Note that, in order to support laziness, the signature of `Foldable`'s 
 `foldRight` is 
 
-```
+```scala
 def foldRight[A, B](fa: F[A], lb: Eval[B])(f: (A, Eval[B]) => Eval[B]): Eval[B]
 ```
 
 as opposed to
 
-```
+```scala
 def foldRight[A, B](fa: F[A], z: B)(f: (A, B) => B): B
 ```
 

docs/src/main/tut/functor.md

@@ -34,11 +34,13 @@ Vector(1,2,3).map(_.toString)
 We can trivially create a `Functor` instance for a type which has a well
 behaved `map` method:
 
-```tut
+```tut:silent
 import cats._
+
 implicit val optionFunctor: Functor[Option] = new Functor[Option] {
   def map[A,B](fa: Option[A])(f: A => B) = fa map f
 }
+
 implicit val listFunctor: Functor[List] = new Functor[List] {
   def map[A,B](fa: List[A])(f: A => B) = fa map f
 }
@@ -48,7 +50,7 @@ However, functors can also be created for types which don't have a `map`
 method. For example, if we create a `Functor` for `Function1[In, ?]`
 we can use `andThen` to implement `map`:
 
-```tut
+```tut:silent
 implicit def function1Functor[In]: Functor[Function1[In, ?]] =
   new Functor[Function1[In, ?]] {
     def map[A,B](fa: In => A)(f: A => B): Function1[In,B] = fa andThen f
@@ -79,10 +81,8 @@ Functor[List].map(List("qwer", "adsfg"))(len)
 is a `Some`:
 
 ```tut
-// Some(x) case: function is applied to x; result is wrapped in Some
-Functor[Option].map(Some("adsf"))(len)
-// None case: simply returns None (function is not applied)
-Functor[Option].map(None)(len)
+Functor[Option].map(Some("adsf"))(len) // Some(x) case: function is applied to x; result is wrapped in Some
+Functor[Option].map(None)(len) // None case: simply returns None (function is not applied)
 ```
 
 ## Derived methods

docs/src/main/tut/kleisli.md

@@ -23,23 +23,26 @@ One of the most useful properties of functions is that they **compose**. That is
 this compositional property that we are able to write many small functions and compose them together
 to create a larger one that suits our needs.
 
-```tut
+```tut:silent
 val twice: Int => Int =
   x => x * 2
 
 val countCats: Int => String =
   x => if (x == 1) "1 cat" else s"$x cats"
 
 val twiceAsManyCats: Int => String =
-  twice andThen countCats
-  // equivalent to: countCats compose twice
+  twice andThen countCats // equivalent to: countCats compose twice  
+```
 
+Thus.
+
+```tut
 twiceAsManyCats(1) // "2 cats"
 ```
 
 Sometimes, our functions will need to return monadic values. For instance, consider the following set of functions.
 
-```tut
+```tut:silent
 val parse: String => Option[Int] =
   s => if (s.matches("-?[0-9]+")) Some(s.toInt) else None
 
@@ -58,7 +61,7 @@ properties of the `F[_]`, we can do different things with `Kleisli`s. For instan
 `FlatMap[F]` instance (we can call `flatMap` on `F[A]` values), we can
 compose two `Kleisli`s much like we can two functions.
 
-```tut
+```tut:silent
 import cats.FlatMap
 import cats.syntax.flatMap._
 
@@ -70,7 +73,7 @@ final case class Kleisli[F[_], A, B](run: A => F[B]) {
 
 Returning to our earlier example:
 
-```tut
+```tut:silent
 // Bring in cats.FlatMap[Option] instance
 import cats.std.option._
 
@@ -87,7 +90,7 @@ It is important to note that the `F[_]` having a `FlatMap` (or a `Monad`) instan
 we can do useful things with weaker requirements. Such an example would be `Kleisli#map`, which only requires
 that `F[_]` have a `Functor` instance (e.g. is equipped with `map: F[A] => (A => B) => F[B]`).
 
-```tut
+```tut:silent
 import cats.Functor
 
 final case class Kleisli[F[_], A, B](run: A => F[B]) {
@@ -117,7 +120,7 @@ resolution will pick up the most specific instance it can (depending on the `F[_
 
 An example of a `Monad` instance for `Kleisli` would be:
 
-```tut
+```tut:silent
 import cats.syntax.flatMap._
 import cats.syntax.functor._
 // Alternatively we can import cats.implicits._ to bring in all the
@@ -179,7 +182,7 @@ That is, we take a read-only value, and produce some value with it. For this rea
 functions often refer to the function as a `Reader`. For instance, it is common to hear about the `Reader` monad.
 In the same spirit, Cats defines a `Reader` type alias along the lines of:
 
-```tut
+```tut:silent
 // We want A => B, but Kleisli provides A => F[B]. To make the types/shapes match,
 // we need an F[_] such that providing it a type A is equivalent to A
 // This can be thought of as the type-level equivalent of the identity function
@@ -210,7 +213,7 @@ Let's look at some example modules, where each module has it's own configuration
 If the configuration is good, we return a `Some` of the module, otherwise a `None`. This example uses `Option` for
 simplicity - if you want to provide error messages or other failure context, consider using `Xor` instead.
 
-```tut
+```tut:silent
 case class DbConfig(url: String, user: String, pass: String)
 trait Db
 object Db {
@@ -229,7 +232,7 @@ data over the web). Both depend on their own configuration parameters. Neither k
 should be. However our application needs both of these modules to work. It is plausible we then have a more global
 application configuration.
 
-```tut
+```tut:silent
 case class AppConfig(dbConfig: DbConfig, serviceConfig: ServiceConfig)
 
 class App(db: Db, service: Service)
@@ -239,7 +242,7 @@ As it stands, we cannot use both `Kleisli` validation functions together nicely
 other a `ServiceConfig`. That means the `FlatMap` (and by extension, the `Monad`) instances differ (recall the
 input type is fixed in the type class instances). However, there is a nice function on `Kleisli` called `local`.
 
-```tut
+```tut:silent
 final case class Kleisli[F[_], A, B](run: A => F[B]) {
   def local[AA](f: AA => A): Kleisli[F, AA, B] = Kleisli(f.andThen(run))
 }
@@ -251,7 +254,7 @@ so long as we tell it how to go from an `AppConfig` to the other configs.
 
 Now we can create our application config validator!
 
-```tut
+```tut:silent
 final case class Kleisli[F[_], Z, A](run: Z => F[A]) {
   def flatMap[B](f: A => Kleisli[F, Z, B])(implicit F: FlatMap[F]): Kleisli[F, Z, B] =
     Kleisli(z => F.flatMap(run(z))(a => f(a).run(z)))

docs/src/main/tut/monad.md

@@ -33,7 +33,7 @@ We can use `flatten` to define `flatMap`: `flatMap` is just `map`
 followed by `flatten`. Conversely, `flatten` is just `flatMap` using
 the identity function `x => x` (i.e. `flatMap(_)(x => x)`).
 
-```tut
+```tut:silent
 import cats._
 
 implicit def optionMonad(implicit app: Applicative[Option]) =
@@ -52,7 +52,7 @@ implicit def optionMonad(implicit app: Applicative[Option]) =
 follows this tradition by providing implementations of `flatten` and `map`
 derived from `flatMap` and `pure`.
 
-```tut
+```tut:silent
 implicit val listMonad = new Monad[List] {
   def flatMap[A, B](fa: List[A])(f: A => List[B]): List[B] = fa.flatMap(f)
   def pure[A](a: A): List[A] = List(a)
@@ -94,7 +94,7 @@ instructions on how to compose any outer monad (`F` in the following
 example) with a specific inner monad (`Option` in the following
 example).
 
-```tut
+```tut:silent
 case class OptionT[F[_], A](value: F[Option[A]])
 
 implicit def optionTMonad[F[_]](implicit F : Monad[F]) = {