Integrate Unidoc with TypelevelSitePlugin

[armanbilge]

So far I've been cheating with javadoc.io URLs but that only works well for single-module projects. Laika supports API docs, so I think that should be easy. The hard part is that although my preference is for sites that are updated on every push, scaladocs should definitely only be updated on tags.

[rossabaker]

Why should scaladocs only be updated on tags? http4s published on push for years. (Counterpoint: this is why the repo is enormous on first clone.)

[armanbilge]

It's because as soon as you add a new method that hasn't been released, the scaladocs are misleading (this happened recently in Cats Effect).

Edit: oh, I guess scaladocs go at a version-specific URL 🤔

Edit 2: e.g. CE just puts them at 3.x:
https://typelevel.org/cats-effect/api/3.x/cats/effect/index.html

[rossabaker]

I would think it's the same basic tradeoffs as the mdocs: you don't want to document unreleased features, but you might not want to do a patch release to fix a typo in the {mdocs, scaladocs}.

[armanbilge]

That's fair. The difference in my eyes is that scaladocs change in ordinary development but mdocs change more deliberately, when we actually write docs 😅

The real solution is what CE is doing now, which is publishing docs from every push to a daily from the 3.3.x branch which is strictly forwards/backwards compatible.

[armanbilge]

To give a concrete example: the ember h2 stuff would already be showing up in http4s scaladocs. But if somebody adds some mdocumentation for it, we can easily hold that PR until the right time to merge.

[rossabaker]

Okay, that's a fair distinction.