tut is a very simple documentation tool for Scala that reads Markdown files and interprets Scala code in tut sheds, allowing you to write documentation that is typechecked and run as part of your build.

The current version is 0.4.3 (changelog here) which runs on Scala 2.10, 2.11, and 2.12 M4/M5.

Projects using tut include doobie and cats. If you're using it and would like be added to the list, please submit a PR!

tut is a Typelevel project. This means we embrace pure, typeful, functional programming, and provide a safe and friendly environment for teaching, learning, and contributing as described in the Typelevel Code of Conduct.

1. Add the following to project/plugins.sbt:

addSbtPlugin("org.tpolecat" % "tut-plugin" % "0.4.3")

2. And add the following to build.sbt:

tutSettings

3. Write a tutorial in src/main/tut/Foo.md:

Here is how you add numbers:
```tut
1 + 1
```

4. At the sbt> prompt type tut, then look at the output in target/<scala-version>/tut/Foo.md:

Here is how you add numbers:
```scala
scala> 1 + 1
res0: Int = 2    
```

tut adds the following commands:

Interpretation obeys the following particulars:

• Each file is interpreted with an independent REPL session. Definitions earlier in the file are available later in the file.
• Each REPL has the same classpath as your build's Test configuration, and by default also has the same scalac options and compiler plugins.
• By default any error in interpretation (compilation failure or runtime exception) will cause the tut command to fail. If this command is part of your CI configuration then your build will fail. Yay!
• tut captures output from the REPL, as well as anything your code writes to standard output (System.out). ANSI escapes are removed from this output, so colorized console output will show up as plaintext.
• In modes that show REPL prompts (see below) blank lines in between statements are discarded and a single blank line is introduced between prompts, as in the normal REPL. Otherwise blank lines are neither introduced nor discarded. This is a change from prior versions.

By default tut will interpret code in tut sheds as if it had been pasted into a Scala REPL. However sometimes you might want a definition without REPL noise, or might want to demonstrate non-compiling code (which would normally cause the build to fail). For these occasions tut provides a number of modifiers that you can add to the shed declaration. For instance,

```tut:silent
import com.woozle.fnord._
```

will produce the following output, suppressing REPL noise:

```scala
import com.woozle.fnord._
```

The following modifiers are supported. Note that you can use multiples if you like; for example you could use tut:silent:fail to show code that doesn't compile, without showing the compilation error.

tut also adds the following sbt settings, all of which have reasonable defaults. It is unlikely that you will need to change any of them, but here you go.

Tut is designed to work seamlessly with sbt-site so that your checked tutorials can be incorporated into your website.

Add the following to project/plugins.sbt in your project to add SBT shell commands:

addSbtPlugin("com.typesafe.sbt" % "sbt-site" % "0.8.1")

Then in your build sbt, link the files generated by tut to your site generation:

project("name").settings(site.addMappingsToSiteDir(tut, "tut"))

When the makeSite task is run in sbt, the typechecked tutorials from src/main/tut will be incorporated with the site generated by sbt-site in target/site.

There are a set of test markdown files and corresponding expected markdown output from tut. Run these tests from sbt with:

publishLocal
tests/scripted

Feedback of any kind is always appreciated.

Issues and PR's are welcome, or just find me on Twitter or #scala on FreeNode or on gitter.