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,66 @@ 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 ~= (_.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/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.
 

docs/expectations.md → docs/features/expectations.md

@@ -1,7 +1,5 @@
----
-id: expectations
-title: Expectations (assertions)
----
+Expectations (assertions)
+=========================
 
 Expectations are pure, composable values. This forces developers to separate the test's checks from the scenario, which is generally cleaner/clearer.
 
@@ -142,7 +140,7 @@ object ExpectationsSuite extends SimpleIOSuite {
     expect(1 != 2) and expect(2 != 1) or expect(2 != 3)
   }
 
-  pureTest("And/Or composition (failure") {
+  pureTest("And/Or composition (failure)") {
     (expect(1 != 2) and expect(2 == 1)) or expect(2 == 3)
   }
 
@@ -228,31 +226,8 @@ object ExpectationsSuite extends SimpleIOSuite {
 }
 ```
 
-```scala mdoc:passthrough
-println(weaver.docs.Output.runSuites(ExpectationsSuite))
-```
-
-## Tracing locations of failed expectations
-
-As of 0.5.0, failed expectations carry a `NonEmptyList[SourceLocation]`, which can be used to manually trace the callsites that lead to a failure.
-
-By default, the very location where the expectation is created is captured, but the `traced` method can be use to add additional locations to the expectation.
-
-```scala mdoc
-object TracingSuite extends SimpleIOSuite {
-
-  pureTest("Tracing example") {
-    foo
-  }
-
-  def foo(implicit loc : SourceLocation) = bar().traced(loc).traced(here)
-
-  def bar() = baz().traced(here)
-
-  def baz() = expect(1 != 1)
-}
-```
+## Example suite report
 
 ```scala mdoc:passthrough
-println(weaver.docs.Output.runSuites(TracingSuite))
+println(weaver.docs.Output.runSuites(ExpectationsSuite))
 ```

docs/filtering.md → docs/features/filtering.md

@@ -1,7 +1,5 @@
----
-id: filtering
-title: Filtering tests
----
+Filtering tests
+===============
 
 When using the IOSuite variants, the user can call `sbt`'s test command as such:
 
@@ -13,4 +11,4 @@ This filter will prevent the execution of any test that doesn't contain the stri
 
 ```
 fooPackage.FooSuite.foo
-```
+```

docs/funsuite.md → docs/features/funsuite.md

@@ -1,7 +1,5 @@
----
-id: funsuite
-title: Pure tests
----
+Pure tests
+==========
 
 If your tests do not require any capability provided by effect-types, you can use a simplified interface `FunSuite`,
 which comes with a single `test` method and does not allow effectful tests.

docs/global_resources.md → docs/features/global_resources.md

@@ -1,7 +1,5 @@
----
-id: global_resources
-title: Sharing resources across suites
----
+Sharing resources across suites
+===============================
 
 ## A word of warning
 

docs/logging.md → docs/features/logging.md

@@ -1,7 +1,5 @@
----
-id: logging
-title: Logging information
----
+Logging information
+===================
 
 Weaver provides each individual test with a lazy-logger. The log statements only get reported if the test is unsuccessful. Because tests in weaver run in parallel by default, this makes it easier to tie printed information to the test it originated from.
 

docs/parallelism.md → docs/features/parallelism.md

@@ -1,7 +1,5 @@
----
-id: parallelism
-title: Configuring parallelism
----
+Configuring parallelism
+=======================
 
 ## Parallelism within suites
 

docs/resources.md → docs/features/resources.md

@@ -1,7 +1,5 @@
----
-id: resources
-title: Sharing resources
----
+Sharing resources
+=================
 
 Resources can be shared across tests, this is done by implementing a method that returns [cats.effect.Resource](https://typelevel.org/cats-effect/datatypes/resource.html).
 

docs/scalacheck.md → docs/features/scalacheck.md

@@ -1,7 +1,5 @@
----
-id: scalacheck
-title: ScalaCheck integration
----
+ScalaCheck integration
+======================
 
 Weaver comes with basic [ScalaCheck](https://www.scalacheck.org/) integration, allowing for property-based testing.
 

docs/specs2.md → docs/features/specs2.md

@@ -1,6 +1,4 @@
----
-id: specs2
-title: specs2 (discontinued)
----
+specs2 (discontinued)
+=====================
 
 The specs2-matchers integration has been dropped in weaver 0.8.0. If you want to test CE code with specs2 UX, please consider using [cats-effect-testing](https://github.com/typelevel/cats-effect-testing).