Feature Request: Verified, but not compiled, code blocks

[djspiewak]

Here's my motivation: I don't want to have to pre-compile my Markdown before making them visible on GitHub. I want to be able to just have plain .md files in my repo, and I want people to be able to view them in final form, with all the code fully intact and highlighting functional.

In short, I want to be able to use scala blocks in my markdown, but I still want documentation verification. This should take two forms.

Compile Verification

First, and most basic, I want the "does it compile" verification that tut provides, but on scala blocks rather than tut blocks:

We can use a `Sink` as a "capstone" to a process network:

```scala
import scalaz.stream._
val p = Process constant 1 take 10
(p to io.stdOutLines run).run
```

The above would be checked for compilation only; no output value checks or transformation would be performed. I would just point tut at my doc/ directory and it would check, but not modify, the files that are there. The same "import carryover" features that are currently available for successive tut blocks in the same document would apply here.

Output Verification

This one takes advantage of an existing convention in the community: denoting line output with // => result where relevant. Again, no transformation of the files is required, but this would allow a form of unit testing in the documentation. Modifying the above slightly:

The results of `observe` are the values that passed through the `Sink`:

```scala
import scalaz.stream._
val p = Process constant 1 take 10
(p observe io.stdOutLines runLog).run    // => Seq(1, 1, 1, 1, 1, 1, 1, 1, 1, 1)
```

The above would be compiled and run, and the output of the last line would be checked against the value to the right of the // =>, when such a symbolic sequence is found at the end of a line. As in the compile verification case, the build would fail if the output does not match, but even in the event that the build passes, no file modifications (or output files!) would be performed.

[tpolecat]

I like it. This would make tut useful even if you're not publishing doc.

[joprice]

This would be great, especially if you just had to add the tut plugin and you get the check for free.

There's also another common case of unmaintained code examples in comments, which this plugin handles:

https://github.com/tkawachi/sbt-doctest

Seems like that tut could also handle this.

[SethTisue]

+1, we are wanting this on the Scala doc site, over at scala/docs.scala-lang#591. ideally we'd redo our render/deploy pipeline to incorporate tut, but at the moment just having it part of PR validation only hits a nice cost/benefit sweet spot

[gabro]

hey @tpolecat is there any update/scheduled work on this?