Cats: Migrate to mdoc

[LukaJCB]

[valydia]

I can give a go to that one if that's ok

[kailuowang]

My concern is that mdoc has a curricular dependency on cats through Paige. It has more dependencies which delay adding Scala 2.13 support

[valydia]

My understanding is that we wouldn't bringing in more dependencies - but switch the way sbt-microsites to use mdoc instead of tut - like that (see the doc):

micrositeCompilingDocsTool := WithMdoc

Wouldn't that be ok this way?

[kailuowang]

Sbt-microsite already has a dependency on mdoc, which is preventing it from supporting Scala 2.13, which is preventing us from generating docs for Scala 2.13 and setting default Scala version to 2.13.

I hope that sbt-microsite makes this dependency on mdoc optional. Right now the circular dependency is only by an unused dependency but if we migrate to mdoc it will be a closer circle.

[valydia]

Fair enough! Thanks for clarifying 👍

[larsrh]

I will tackle this issue. It'll hopefully unblock #3368.

[larsrh]

I've stopped working on it because there are too many issues blocking a straightforward migration.

[jhnsmth]

BTW @travisbrown also gave it a try while working on #3218

I will try to look into this on the next weekend

[travisbrown]

@larsrh Sorry I missed your comment last week, but yeah, I took an initial stab at this in December when I updated to sbt-microsites 1.x, and then tried again last month, when I spent a couple of hours trying to add nest and reset-object and some new invisible blocks to get things to work, and it's just an enormous horrible chore.

A couple of issues I ran into have been reported and resolved (e.g. https://github.com/scalameta/mdoc/pull/306), but there are still lots of weird things going on. I kept crashing the compiler with stuff like unexpected multiple results for a companion symbol lookup for object Pair, etc., I think largely because once you start adding nest the locally blocks can get pretty deep, and the compiler just doesn't handle that kind of thing very robustly. I didn't look very deeply into those issues, though.

@jhnsmth It would be a huge service to everyone if you could do this, but it's not going to be fun.

[travisbrown]

(For what it's worth maybe the worst part is the extremely slow turnaround time during development—you change something and then wait 35 seconds to get the next error message. If I were going to try this again I'd probably try to set something up where I could run mdoc on individual pages, possibly outside of the sbt build altogether, just so I could get faster feedback. I didn't really look into that, though.)

[keynmol]

I'll try to give this a go (if anything, add my username to the tombstone of people that tried), because I've done the same thing for my ongoing migration of squants' docs

[keynmol]

@travisbrown regarding faster feedback, I've realised mdoc allows argument override when you shellout to Mdoc process:

sbt> docs/mdoc --in docs/src/main/tut/typeclasses/ --watch

Which means you can run mdoc in watch mode (hot compiler, much faster recompilation), and also run on individual files and folders.

This helps a lot

[keynmol]

This should be ready: https://github.com/typelevel/cats/pull/3595