Site plugin

[armanbilge]

Towards #44.

I was curious, and couldn't help myself. This patches together a proof-of-concept microsite-plugin with a minimally configured Laika just to see what would happen. Here's what pops out: https://armanbilge.github.io/sbt-typelevel

[rossabaker]

I don't love the name "microsite", which I think is associated with the sbt-microsites plugin. I was expecting to find Jekyll here and be grumpy about it.

I do think having this will be a big win.

[armanbilge]

Ok, pending bikeshed of "microsite" (maybe just "site"?), I think this is in a reasonable place. It configures a basic mdoc/laika site with some Typelevely things and generates a CI job to build and publish the site.

I'm hopeful we can use this to replace the Jekyll-based sites. The theme colors and other details can definitely be improved but that can happen in follow-up work and easily be propagated across all Typelevel projects.

[armanbilge]

Updated the site at https://armanbilge.github.io/sbt-typelevel.

[armanbilge]

I'd like to land this. Any feelings about the default, which publishes the site on every push?

[rossabaker]

The problem with publishing on every push is that you can document features that are unreleased. The problem with publishing on tags is you need to do a patch release to correct a typo in your docs. There's no perfect default, so pick your poison.

[armanbilge]

Yep, the age-old question. I like the publish-on-push default, making the following assumptions:

1. Many new features go undocumented for a while anyway 🙃
2. Seems like most docs PRs are fixing/adding docs for existing things, typos, etc. These should go live ASAP.
3. It's easier / makes more sense to hold a docs PR for a more appropriate time to merge than it is to turn every docs PR into a patch release.
4. For smaller projects that essentially Do One Thing, new features are often quickly followed by a release.
5. For bigger projects, more custom solutions are needed anyway, e.g. to support multi-versioned docs. Docs can also be published from pushes to a patch branch e.g. series/3.3.x while feature development occurs on e.g. series/3.x (this is what CE is doing rn.)

Note I'm making a distinction here between the site/mdocs vs the API scaladocs. API scaladocs should definitely not be published on every push, as they get out of sync with the latest release quickly. This plugin doesn't publish scaladocs, but I have future ideas for this.