Migrate documentation to Laika (sbt-typelevel-site)

.github/workflows/ci.yml

@@ -80,11 +80,11 @@ jobs:
 
       - name: Make target directories
         if: github.event_name != 'pull_request' && (startsWith(github.ref, 'refs/tags/v') || github.ref == 'refs/heads/main')
-        run: mkdir -p modules/scalacheck/native/target modules/framework-cats/native/target modules/framework/jvm/target modules/core/native/target modules/framework/native/target modules/core/js/target modules/framework/js/target modules/core/jvm/target modules/core-cats/native/target modules/discipline/native/target modules/core-cats/js/target modules/framework-cats/js/target modules/framework-cats/jvm/target modules/discipline/js/target modules/scalacheck/jvm/target modules/discipline/jvm/target modules/core-cats/jvm/target modules/scalacheck/js/target project/target
+        run: mkdir -p modules/scalacheck/native/target modules/framework-cats/native/target modules/framework/jvm/target modules/docs/jvm/target modules/core/native/target modules/framework/native/target modules/core/js/target modules/framework/js/target modules/core/jvm/target modules/core-cats/native/target modules/discipline/native/target modules/core-cats/js/target modules/framework-cats/js/target modules/framework-cats/jvm/target modules/discipline/js/target modules/scalacheck/jvm/target modules/discipline/jvm/target modules/core-cats/jvm/target modules/scalacheck/js/target project/target
 
       - name: Compress target directories
         if: github.event_name != 'pull_request' && (startsWith(github.ref, 'refs/tags/v') || github.ref == 'refs/heads/main')
-        run: tar cf targets.tar modules/scalacheck/native/target modules/framework-cats/native/target modules/framework/jvm/target modules/core/native/target modules/framework/native/target modules/core/js/target modules/framework/js/target modules/core/jvm/target modules/core-cats/native/target modules/discipline/native/target modules/core-cats/js/target modules/framework-cats/js/target modules/framework-cats/jvm/target modules/discipline/js/target modules/scalacheck/jvm/target modules/discipline/jvm/target modules/core-cats/jvm/target modules/scalacheck/js/target project/target
+        run: tar cf targets.tar modules/scalacheck/native/target modules/framework-cats/native/target modules/framework/jvm/target modules/docs/jvm/target modules/core/native/target modules/framework/native/target modules/core/js/target modules/framework/js/target modules/core/jvm/target modules/core-cats/native/target modules/discipline/native/target modules/core-cats/js/target modules/framework-cats/js/target modules/framework-cats/jvm/target modules/discipline/js/target modules/scalacheck/jvm/target modules/discipline/jvm/target modules/core-cats/jvm/target modules/scalacheck/js/target project/target
 
       - name: Upload target directories
         if: github.event_name != 'pull_request' && (startsWith(github.ref, 'refs/tags/v') || github.ref == 'refs/heads/main')
@@ -265,5 +265,42 @@ jobs:
       - name: Submit Dependencies
         uses: scalacenter/sbt-dependency-submission@v2
         with:
-          modules-ignore: rootjs_2.12 rootjs_2.13 rootjs_3 rootjvm_2.12 rootjvm_2.13 rootjvm_3 rootnative_2.12 rootnative_2.13 rootnative_3
+          modules-ignore: rootjs_2.12 rootjs_2.13 rootjs_3 weaver-docs_2.12 weaver-docs_2.13 weaver-docs_3 rootjvm_2.12 rootjvm_2.13 rootjvm_3 rootnative_2.12 rootnative_2.13 rootnative_3
           configs-ignore: test scala-tool scala-doc-tool test-internal
+
+  site:
+    name: Generate Site
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        java: [temurin@11]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout current branch (full)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Java (temurin@11)
+        id: setup-java-temurin-11
+        if: matrix.java == 'temurin@11'
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 11
+          cache: sbt
+
+      - name: sbt update
+        if: matrix.java == 'temurin@11' && steps.setup-java-temurin-11.outputs.cache-hit == 'false'
+        run: sbt +update
+
+      - name: Generate site
+        run: sbt docs/tlSite
+
+      - name: Publish site
+        if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+        uses: peaceiris/[email protected]
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: site/target/docs/site
+          keep_files: true

build.sbt

@@ -1,3 +1,13 @@
+import laika.helium.config.TextLink
+import laika.helium.config.ReleaseInfo
+import laika.helium.config.HeliumIcon
+import laika.helium.config.IconLink
+import laika.helium.config.LinkGroup
+import laika.helium.config.VersionMenu
+import laika.ast.Path.Root
+import laika.ast.Image
+import laika.config.LinkValidation
+import org.typelevel.sbt.site.TypelevelSiteSettings
 import sbt.librarymanagement.Configurations.ScalaDocTool
 
 // https://typelevel.org/sbt-typelevel/faq.html#what-is-a-base-version-anyway
@@ -16,12 +26,15 @@ ThisBuild / tlCiHeaderCheck := false
 // publish to s01.oss.sonatype.org (set to true to publish to oss.sonatype.org instead)
 ThisBuild / tlSonatypeUseLegacyHost := false
 
+// enable the sbt-typelevel-site laika documentation
+ThisBuild / tlSitePublishBranch := Some("main")
+
 // use JDK 11
 ThisBuild / githubWorkflowJavaVersions := Seq(JavaSpec.temurin("11"))
 
-val scala212 = "2.12.17"
-val scala213 = "2.13.10"
-ThisBuild / crossScalaVersions := Seq(scala212, scala213, "3.3.1")
+val scala212 = "2.12.18"
+val scala213 = "2.13.12"
+ThisBuild / crossScalaVersions := Seq(scala212, scala213, "3.3.3")
 ThisBuild / scalaVersion       := scala213 // the default Scala
 
 val Version = new {
@@ -38,6 +51,8 @@ val Version = new {
   val scalajsStubs           = "1.1.0"
   val testInterface          = "1.0"
   val scalacCompatAnnotation = "0.1.4"
+  val http4s                 = "0.23.26"
+  val http4sBlaze            = "0.23.16"
 }
 
 lazy val root = tlCrossRootProject.aggregate(core,
@@ -151,3 +166,67 @@ lazy val discipline = crossProject(JVMPlatform, JSPlatform, NativePlatform)
       "org.typelevel" %%% "cats-laws"       % Version.catsLaws % Test
     )
   )
+
+lazy val docsOutput = crossProject(JVMPlatform)
+  .in(file("modules/docs"))
+  .dependsOn(core, framework, coreCats, cats, scalacheck, discipline)
+  .settings(
+    moduleName := "docs",
+    name       := "output for documentation",
+    watchSources += (ThisBuild / baseDirectory).value / "docs",
+    libraryDependencies ++= Seq(
+      "org.http4s"    %% "http4s-dsl"          % Version.http4s,
+      "org.http4s"    %% "http4s-blaze-server" % Version.http4sBlaze,
+      "org.http4s"    %% "http4s-blaze-client" % Version.http4sBlaze,
+      "com.lihaoyi"   %% "fansi"               % "0.2.7",
+      "org.typelevel" %% "cats-kernel-laws"    % Version.catsLaws
+    )
+  )
+
+lazy val docs = project
+  .in(file("site"))
+  .enablePlugins(TypelevelSitePlugin)
+  .dependsOn(
+    core.jvm,
+    framework.jvm,
+    coreCats.jvm,
+    cats.jvm,
+    scalacheck.jvm,
+    discipline.jvm,
+    docsOutput.jvm)
+  .settings(
+    moduleName := "weaver-docs",
+    name       := "Weaver documentation",
+    watchSources += (ThisBuild / baseDirectory).value / "docs",
+    libraryDependencies ++= Seq(
+      "org.http4s"    %% "http4s-dsl"          % Version.http4s,
+      "org.http4s"    %% "http4s-blaze-server" % Version.http4sBlaze,
+      "org.http4s"    %% "http4s-blaze-client" % Version.http4sBlaze,
+      "org.typelevel" %% "cats-laws"           % Version.catsLaws
+    ),
+    tlSiteHelium ~= (_.site.internalCSS(Root / "assets")
+      .site.landingPage(
+        logo = Some(Image.internal(Root / "assets/logo.png")),
+        title = Some("Weaver"),
+        subtitle = Some("A test framework that runs everything in parallel."),
+        latestReleases = Seq(
+          ReleaseInfo("Upcoming Stable Release", "1.0.0")
+        ),
+        license = Some("Apache2"),
+        titleLinks = Seq(
+          VersionMenu.create(unversionedLabel = "Getting Started"),
+          LinkGroup.create(
+            IconLink.external("https://github.com/typelevel/weaver-test",
+                              HeliumIcon.github),
+            IconLink.external("https://discord.gg/XF3CXcMzqD", HeliumIcon.chat)
+          )
+        ),
+        documentationLinks = Seq(
+          TextLink.internal(Root / "overview/installation.md", "Installation"),
+          TextLink.internal(Root / "features/expectations.md",
+                            "Expectations (Assertions)")
+        )
+      )),
+    laikaConfig ~= (_.withConfigValue(LinkValidation.Global(excluded =
+      Seq(Root / "assets"))).withRawContent)
+  )

docs/assets/custom.css

@@ -0,0 +1,11 @@
+div.terminal {
+  color: white;
+  background-color: black;
+}
+
+div.terminal pre {
+  background-color: black;
+  color: white;
+  padding: 20px;
+  overflow: auto
+}

docs/assets/sample_expectation_suite_output.html

@@ -0,0 +1,136 @@
+<!DOCTYPE html>
+<html>
+<head>
+<style>
+div.terminal {
+  color: white;
+  background-color: black;
+}
+div.terminal pre {
+  background-color: black;
+  color: white;
+  padding: 20px;
+  overflow: auto
+}
+</style>
+<body>
+```scala mdoc:passthrough
+import weaver._
+import cats.effect.IO
+
+object ExpectationsSuite extends SimpleIOSuite {
+
+  object A {
+    object B {
+      object C {
+        def test(a: Int) = a + 5
+      }
+    }
+  }
+
+  pureTest("Simple expectations (success)") {
+    val z = 15
+
+    expect(A.B.C.test(z) == z + 5)
+  }
+
+  pureTest("Simple expectations (failure)") {
+    val z = 15
+
+    expect(A.B.C.test(z) % 7 == 0)
+  }
+
+
+  pureTest("And/Or composition (success)") {
+    expect(1 != 2) and expect(2 != 1) or expect(2 != 3)
+  }
+
+  pureTest("And/Or composition (failure") {
+    (expect(1 != 2) and expect(2 == 1)) or expect(2 == 3)
+  }
+
+  pureTest("Varargs composition (success)") {
+    // expect(1 + 1 == 2) && expect (2 + 2 == 4) && expect(4 * 2 == 8)
+    expect.all(1 + 1 == 2, 2 + 2 == 4, 4 * 2 == 8)
+  }
+
+  pureTest("Varargs composition (failure)") {
+    // expect(1 + 1 == 2) && expect (2 + 2 == 4) && expect(4 * 2 == 8)
+    expect.all(1 + 1 == 2, 2 + 2 == 5, 4 * 2 == 8)
+  }
+
+  pureTest("Working with collections (success)") {
+    forEach(List(1, 2, 3))(i => expect(i < 5)) and
+      forEach(Option("hello"))(msg => expect.same(msg, "hello")) and
+      exists(List("a", "b", "c"))(i => expect(i == "c")) and
+      exists(Vector(true, true, false))(i => expect(i == false))
+  }
+
+  pureTest("Working with collections (failure 1)") {
+    forEach(Vector("hello", "world"))(msg => expect.same(msg, "hello"))
+  }
+
+  pureTest("Working with collections (failure 2)") {
+    exists(Option(39))(i => expect(i > 50))
+  }
+
+  import cats.Eq
+  case class Test(d: Double)
+
+  implicit val eqTest: Eq[Test] = Eq.by[Test, Double](_.d)
+
+  pureTest("Strict equality (success)") {
+    expect.eql("hello", "hello") and
+      expect.eql(List(1, 2, 3), List(1, 2, 3)) and
+      expect.eql(Test(25.0), Test(25.0))  
+  }
+
+  pureTest("Strict equality (failure 1)") {
+    expect.eql("hello", "world")
+  }
+
+  pureTest("Strict equality (failure 2)") {
+    expect.eql(List(1, 2, 3), List(1, 19, 3))
+  }
+
+  pureTest("Strict equality (failure 3)") {
+    expect.eql(Test(25.0), Test(50.0))
+  }
+
+  // Note that we don't have an instance of Eq[Hello]
+  // anywhere in scope
+  class Hello(val d: Double) {
+    override def toString = s"Hello to $d"
+
+    override def equals(other: Any) = 
+      if(other != null && other.isInstanceOf[Hello])
+        other.asInstanceOf[Hello].d == this.d
+      else 
+        false
+  }
+
+  pureTest("Relaxed equality comparison (success)") {
+    expect.same(new Hello(25.0), new Hello(25.0))
+  }
+
+  pureTest("Relaxed equality comparison (failure)") {
+    expect.same(new Hello(25.0), new Hello(50.0))
+  }
+
+  pureTest("Non macro-based expectations") {
+    val condition : Boolean = false
+    if (condition) success else failure("Condition failed")
+  }
+
+  test("Failing fast expectations") {
+    for {
+      h <- IO.pure("hello")
+      _ <- expect(h.isEmpty).failFast
+    } yield success
+  }
+}
+println(weaver.docs.Output.runSuites(ExpectationsSuite))
+```
+</body>
+</head>
+</html>

docs/directory.conf

@@ -0,0 +1,6 @@
+laika.navigationOrder = [
+  overview,
+  features,
+  samples,
+  faqs
+]

docs/faqs/directory.conf

@@ -0,0 +1,5 @@
+laika.title = Frequently Asked Questions
+laika.navigationOrder = [
+  ide_faqs.md,
+  other_effects.md
+]

docs/faqs.md → docs/faqs/ide_faqs.md

@@ -1,13 +1,11 @@
----
-id: faqs 
-title: Frequently Asked Questions
----
+IDE Support?
+==========================
 
-## How do I get weaver working with IntelliJ / vscode / neovim ?
+## How do I get weaver working with IntelliJ / vscode / neovim?
 
 Weaver provides a JUnit runner that IDEs pick up automatically. On IntelliJ the suite should have the normal button to run the tests, and Metals should provide a code lens.
 
-## How do I ignore individual tests ?
+## How do I ignore individual tests?
 
 An `.ignore` extension method is provided on strings, and can be used when declaring tests. All tests that are tagged with `.ignore` will be ignored in the test suite, including any that are tagged with `.only`.
 

docs/other_effects.md → docs/faqs/other_effects.md

@@ -1,8 +1,5 @@
----
-id: other_effects
-
-title: Other effects
----
+What happened to ZIO / Monix / MonixBIO ?
+=============
 
 Starting with version 0.8.0, Weaver no longer offers out-of-the-box support for other effect types
 than cats-effect.

docs/features/directory.conf

@@ -0,0 +1,15 @@
+laika.title = Features
+laika.navigationOrder = [
+ expectations.md,
+ tracing_failures.md,
+ resources.md,
+ global_resources.md,
+ logging.md,
+ tagging.md,
+ scalacheck.md,
+ discipline.md,
+ parallelism.md,
+ funsuite.md,
+ filtering.md,
+ specs2.md
+]

docs/discipline.md → docs/features/discipline.md

@@ -1,7 +1,5 @@
----
-id: discipline
-title: Discipline integration
----
+Discipline integration
+======================
 
 Weaver comes with basic [Discipline](https://github.com/typelevel/discipline) integration, allowing property-based law testing.