implement Snippet mechanism like Paradox

[eed3si9n]

This implements low-tech solution for compiled documentation, inspired by Lightbend Paradox's snippet feature. It's low tech because this feature itself just grabs the referenced file as a code block and includes it, and assumes compile or other validation is done elsewhere. (In our case we are using scripted) This low tech approach is nice because it's fast.

// This includes the entire file as Scala code snippet
@@snip [build.sbt]($root$/src/sbt-test/ref/basic/build.sbt) {}

or

// This includes snippet between a line containing #example another line with #example
@@snip [build.sbt]($root$/src/sbt-test/ref/basic/build.sbt) { #example }

or

// This specifies syntax highlight
@@snip [build.sbt]($root$/src/sbt-test/ref/basic/build.sbt) { #example type=text }

There's a hard-coded treatment for $root$, which is interpreted to be the root of the build. Otherwise, the path is treated to the relative path from the markdown file.

[dwijnand]

Oh the dilemma.. not having these code blocks inline is a major pain, but enforcing that they're absolutely correct is a great benefit..

Any chance we can refine this to leave them inline?

[eed3si9n]

@dwijnand Well, if we are compatible with Paradox behavior this is how it works.

If we leave anything in but not sync it, then it's confusing.

So a way it work might be:

@@snip [build.sbt]($root$/src/sbt-test/ref/basic/build.sbt) {}

<!-- SNIIPPET BEGIN. DO NOT EDIT MANUALLY -->
```
lazy val root ...
```
<!-- END SNIIPPET -->

and during the "compile"-time we just remove @@snip line and HTML-comment (Pamflet unfortunately doesn't support HTML-comment foundweekends/pamflet#70).

[dwijnand]

I was hoping to have the same behaviour as tut, where you can just write:

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

So I guess ideally we'd have:

Use the following build definition:
```sbt
val root = project in file(".")
```

[eed3si9n]

I've tried that approach with sbt-pamflet https://github.com/sbt/sbt-pamflet, and it's super slow. Besides, I am not sure if that makes sense for builds.

If you are suggesting that we go the opposite direction by generating scripted out of snippet, I don't think it would always work out since we often want part of the code, not the whole thing.

[eed3si9n]

I think we should merge this as is for now, also for the Paradox compatibility.
If you were considering Paradox, then we should keep the snippet syntax the same.

I want to move on and focus my energy on actually documenting things using this feature.