Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Publish the website to sonatype/maven #317

Draft
wants to merge 15 commits into
base: main
Choose a base branch
from
Draft

Conversation

armanbilge
Copy link
Member

Another strategy for #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?

@mergify mergify bot added the site label Jun 22, 2022
@valencik
Copy link
Member

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
Copy link
Member Author

armanbilge commented Jun 22, 2022

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

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

Nice to have

  • 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.
  • Version selector jumps to corresponding page, or a fallback if not relevant. (Laika does this.)
    Yes, javadoc.io also does this :)
  • If a PR will break the site generator, it fails. (A risk if mdoc compilation is separate from site generation.)

Extra credit

  • /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.
  • Works across repos for polyrepo projects (subdomains are a viable alternative)
    TBH not sure what Ross wants here :) but this basically works everywhere.
  • 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 armanbilge marked this pull request as ready for review July 1, 2023 20:13
@armanbilge armanbilge changed the title POC: publish the website to sonatype/maven Publish the website to sonatype/maven Jul 1, 2023
@armanbilge
Copy link
Member Author

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

@armanbilge armanbilge marked this pull request as draft July 1, 2023 20:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants