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.8 (changelog here) which runs on Scala 2.10, 2.11, and 2.12.
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.
Quick Start (sbt)
1. Add the following to
addSbtPlugin("org.tpolecat" % "tut-plugin" % "0.4.8")
2. And add the following to
3. Write a tutorial in
Here is how you add numbers: ```tut 1 + 1 ```
4. At the
sbt> prompt type
tut, then look at the output in
Here is how you add numbers: ```scala scala> 1 + 1 res0: Int = 2 ```
Quick Start (standalone)
In case you want to run tut without sbt, you can use coursier instead.
1. Install the coursier command-line launcher.
2. Run tut:
coursier launch -r "https://dl.bintray.com/tpolecat/maven/" org.tpolecat:tut-core_2.11:0.4.8 -- \ in out '.*\.md$' -classpath $(coursier fetch -p com.chuusai:shapeless_2.11:2.3.1)
This will process all
*.md files in
in, write them to
out, while providing
com.chuusai:shapeless_2.11:2.3.1 in the classpath.
Note that the Scala library always needs to be in the classpath.
tut adds the following commands:
||Moves the contents of
||Does the same thing as
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
Testconfiguration, 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
tutcommand 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.
||Code in the shed must throw an exception or fail to compile. Successful interpretation will cause a buid failure.|
||Code in the shed might throw an exception or fail to compile. Such failure will not cause a build failure. Note that this modifier is deprecated in favor of
||Suppresses REPL prompts and output; under this modifier the input and output text are identical.|
||Output will not have
||Suppresses all output. This is not recommended since the point of tut is to provide code that the user can type in and expect to work. But in rare cases you might want one of these at the bottom of your file to clean up filesystem mess that your code left behind.|
||Output will be suitable for copy and paste into the REPL. That is, there are no REPL prompts or margins, and output from the REPL is commented.|
||Suppresses REPL prompts and input statement, output only will be the evaluated statement.|
||Decorates the output scala code block with
||Resets the REPL state prior to evaluating the code block. Use this option with care, as it has no visible indication and can be confusing to readers who are following along in their own REPLs.|
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.
||Location of tut source files.||
||Regex specifying files that should be interpreted.||Names ending in
||Destination for tut output.||
||Compiler options that will be passed to the tut REPL.||Same as
||List of compiler plugin jarfiles to be passed to the tut REPL.||Same as
Integration with sbt-microsites
The sbt-microsites plugin uses tut and sbt-site and some other odds and ends to turn your documentation into a really nice little website. It is entirely excellent and I recommend it highly.
Integration with sbt-site
If you wish to use tut with sbt-site 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:
makeSite task is run in sbt, the typechecked tutorials from
src/main/tut will be incorporated with the site generated by sbt-site in
Running the Tests
There are a set of test markdown files and corresponding expected markdown output from tut. Run these tests from sbt with:
Complaints and other Feedback
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.