How to write Scala documentation with runnable snippets, similar to mdbook?

Question

The Rust tool mdbook generates documentation from Markdown. It lets the reader edit and run Rust snippets directly in the browser by piping them to the Rust Playground. This lets you write readable documentation while letting your reader try out examples without cut-and-paste into a local editor. The Rust documentation uses this.

Is there anything like this for Scala? Scala has a playground (SCastie) so it seems the hard part has been dealt with. Perhaps there is a more general tool like gitbook that can do this by configuring SCastie as a backend?

Answer 1

Mdoc allows creating SCastie snippets out of your code.

From docs:

Before:

```scala mdoc:scastie
val x = 1 + 2
println(x)
```

After:

<script src="https://scastie.scala-lang.org/embedded.js"></script>
<pre class='scastie-snippet-2bc0b4f2-db76-4c68-8e7f-3a472d59c50d'></pre>
<script>window.addEventListener('load', function() {
 scastie.Embedded('.scastie-snippet-2bc0b4f2-db76-4c68-8e7f-3a472d59c50d', {
   code: `val x = 1 + 2
println(x)`,
   theme: 'light',
    isWorksheetMode: true,
    targetType: 'jvm',
    scalaVersion: '2.12.6'
  })
})</script>

Answer 2

You can make scalafiddle snippets. See the documentation at https://github.com/scalafiddle/scalafiddle-core/blob/master/integrations/README.md