Migrate from tut to mdoc

[ckipp01]

Before I go to much further I wanted to throw this up here to make sure the direction was ok. Mainly there are a few key differences between tut and mdoc that you'll see right away, but the main one is the following:

val a = 1
val a = 2

In the above, this will compile fine with tut whereas even if you have two separate code blocks in a page like so:

val a = 1

val a = 2

This will not compile with mdoc as the document is combined and compiled as a normal Scala program. There are a couple workarounds for this.

1. Use mdoc:nest which will wrap the code blocks in scala.Predef.locally{...} so the above wouldn't be an issue.
2. Use mdoc:reset which will reset everything so again you could redefine a variable. Often nest is recommended to still keep the imports that may have been defined earlier for further blocks.

From the handful of them that I've done so far in _ba I don't really think the usage of :nest or :reset will matter that much mostly because there isn't a lot of imports like you'd normally see in a library using this for their docs. Or, is some cases each block already includes the imports so they can stand alone. There is a chance depending on the document that I would use :nest is some places and :reset in others. If the direction of this looks fine, I'll continue on as I have been.

When finished this will close #1815

[SethTisue]

looks great!

mildly curious, why mdoc_2.12 and not mdoc_2.13?

[ckipp01]

looks great!

Cool, I'll carry on then.

mildly curious, why mdoc_2.12 and not mdoc_2.13?

No reason at all, it was on 2.12 of tut before, so I quickly kept the same for mdoc, but I'll bump it to 2.13.

EDIT: Lied a bit, if I do bump to 2.13 there are a few small things I hit on. They are easily fixable, but they require changing some code snippets. So I'll probably keep at 2.12, make all the mdoc changes first, and then do another follow-up pr bumping to 2.13 to separate the mdoc switch from any Scala code block changes.

[ckipp01]

So this should now be ready to go. Since there are a ton of changes here, I'll simply outline a few:

• run-tut.sh -> run-mdoc.sh (largely the same but just using mdoc)
• tut_replace.rb -> mdoc_replace.rb (again largely the same just searching for the various mdoc modifiers now instead of tut)
• scripts/ci.sh updated to call run-mdoc.sh
• New section in contribute.md to explain mdoc, how to use it, and it includes some examples

Other than that, it changing all tut references to mdoc and then adding :nest, :reset, :fail, or :crash modifiers where needed. I tried hard not to actually touch any code content while doing this. There was only one or two places where I made a slight change just to get it to compile.

[SethTisue]

fantastic, thank you so much for this!!