Doctests

[julian-zucker]

Is your documentation request related to a problem? Please describe.
Code examples in our documentation can fall behind the actual code. If an API changes, the example may no longer run. This is confusing for users.

Describe the documentation you'd like
Not really "documentation I'd like", but I want a tool that will run all scala code examples in our docs, like doctest for python. This tool should be bundled in overcommit and travis.

Additional context
In PR #64, we had to update documentation, and could easily have forgotten. Automating the checking of documentation is good, and will make us less afraid to put code examples in documentation!

[ubaldop]

Did you consider tut?

[julian-zucker]

Tut looks like what we want! Run markdown tests, and generating MD output. Thanks for the suggestion!

[ubaldop]

You're welcome 😉
However, afaik, tut only exists as sbt plugin. Since you're using Maven it'd require few refinements in order to be introduced here.
I mean, for example, it'd be necessary to wrap tut in a Maven plugin.

[drassaby]

Looks like tut is now deprecated. They recommend using mdoc, which has both an sbt plugin and command-line version