underscoreio/tut

Name: tut

Owner: Underscore

Description: doc/tutorial generator for scala

Created: 2015-11-21 18:31:36.0

Updated: 2016-11-09 14:05:18.0

Pushed: 2016-07-05 07:16:14.0

Homepage:

Size: 469

Language: Scala

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

tut

<img alt=“How'd you get so funky?” align=right src=“tut.jpg”/>

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.2 (changelog here) which runs on Scala 2.10, 2.11, and 2.12 (as of 2.12.0-M3).

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.

Quick Start

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

btPlugin("org.tpolecat" % "tut-plugin" % "0.4.2")

2. And add the following to build.sbt:

ettings

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    
```

Commands

tut adds the following commands:

| Command | Explanation | |———-|————-| | tut | Moves the contents of tutSourceDirectory into tutTargetDirectory, interpreting code in tut sheds in any file whose name matches tutNameFilter (other files are copied but not interpreted). | | tutOnly | Does the same thing as tut but only for the specified path under tutSourceDirectory. Note that tab completion works for this command |

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.

Modifiers

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.

| Modifier | Explanation | |————-|————-| | :fail | Code in the shed must throw an exception or fail to compile. Successful interpretation will cause a buid failure. | | :nofail | 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 :fail. | | :silent | Suppresses REPL prompts and output; under this modifier the input and output text are identical. | | :plain | Output will not have scala syntax highlighting. | | :invisible | 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. | | :book | 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. | | :reset | 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. |

Settings

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.

| Setting | Explanation | Default Value | |———|————-|—————| | tutSourceDirectory | Location of tut source files. | sourceDirectory.value / "main" / "tut" | | tutNameFilter | Regex specifying files that should be interpreted. | Names ending in .md .txt .htm .html | | tutTargetDirectory | Destination for tut output. | crossTarget.value / "tut" | | tutScalacOptions | Compiler options that will be passed to the tut REPL. | Same as Test configuration. | | tutPluginJars | List of compiler plugin jarfiles to be passed to the tut REPL. | Same as Test configuration. |

Integration with sbt-site

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:

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

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

ect("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.

Running the Tests

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

ishLocal
s/scripted

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.