Publish the website to sonatype/maven

[armanbilge]

Another strategy for https://github.com/typelevel/sbt-typelevel/issues/100. /cc @rossabaker

The idea is simple, and inspired by the success we've had publishing unidocs. In this case, we package up the Laika-generated website as a Javadoc artifact and publish it. Then, stable versions can be browsed at javadoc.io (with their handy version-picker!) and snapshots via Sonatype's own hosting infrastructure, like so:

https://s01.oss.sonatype.org/service/local/repositories/snapshots/archive/org/typelevel/sbt-typelevel-website_2.12/0.4.12-20-fb939ca-SNAPSHOT/sbt-typelevel-website_2.12-0.4.12-20-fb939ca-SNAPSHOT-javadoc.jar/!/index.html

The motivation is that setting up and maintaining versioned documentation is hard, even with Laika's integrated support for this. It's a lot of overhead for smaller projects that probably have only one active version at a time, but want to keep old documentation available as well.

Now, we have a stable destination to host these old versions of the site. Meanwhile, the current, live version of the site can be hosted on GH pages.

Thoughts?

[valencik]

This is a surprisingly low amount of code to get it running, neat.

I like that the docs would be an immutable artifact along with the code artifacts.

Do you know off hand if this addresses any of the remaining checklist items?

• [ ] EOL versions can easily point to a maintained version
• [ ] /stable/* redirects to the latest stable version, like Read The Docs. This was possible on Netlify, which is an administrative headache. This is impossible on gh-pages.
• [ ] Works across repos for polyrepo projects (subdomains are a viable alternative)
• [ ] EOL versions are not indexed by Google. (Maybe. This would improve SEO within the site, but could hurt it to the site.)

[armanbilge]

Thanks! Yes, all credit to Laika again for already doing the right thing with mappings :) Note that there is still some work to be done to figure out how to fit this in the CI pipeline, currently the docs are re-built during the publishing step which is sub-optimal.

Good question, let me actually go through Ross's entire checklist:

Table Stakes

• [x] Each maintained branch gets its own set of docs Kind of. In this case, every versioned release has its own docs.
• [x] Can publish from maintenance branches without breaking new things
• [x] Can publish from main without breaking old things

Nice to have

• [x] A new version updates the version selector in old versions Javadoc.io does this for us :)
• [ ] EOL versions can easily point to a maintained version No. We cannot change docs once they are published; they are permanent.
• [x] Version selector jumps to corresponding page, or a fallback if not relevant. (Laika does this.) Yes, javadoc.io also does this :)
• [x] If a PR will break the site generator, it fails. (A risk if mdoc compilation is separate from site generation.)

Extra credit

• [x] /stable/* redirects to the latest stable version, like Read The Docs. This was possible on Netlify, which is an administrative headache. This is impossible on gh-pages. javadoc.io does support latest, but this will give you a milestone. Note that under this strategy, you can just publish stable docs to GH pages and point to javadoc.io to browse other versions.
• [x] Works across repos for polyrepo projects (subdomains are a viable alternative) TBH not sure what Ross wants here :) but this basically works everywhere.
• [x] EOL versions are not indexed by Google. (Maybe. This would improve SEO within the site, but could hurt it to the site.) Seems like javadoc.io supports indexing with helpful sitemaps. https://javadoc.io/robots.txt Oh, but note that the sitemaps only include the latest version ... https://javadoc.io/sitemap/org.typelevel/feral-lambda-http4s_2.13/sitemap.xml

[armanbilge]

Gah, I'm not happy with anything after a953d7a162e885f9c06a89d943295f3e09380651. Everything got much more entangled and complicated, hmm.