Refactor/2024 07 renewal of documentation

.github/workflows/ci.yml

@@ -328,6 +328,59 @@ jobs:
 
       - run: scala-steward validate-repo-config .scala-steward.conf
 
+  site:
+    name: Generate Site
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        java: [corretto@11]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Install sbt
+        uses: sbt/setup-sbt@v1
+
+      - name: Checkout current branch (full)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Java (corretto@11)
+        id: setup-java-corretto-11
+        if: matrix.java == 'corretto@11'
+        uses: actions/setup-java@v4
+        with:
+          distribution: corretto
+          java-version: 11
+          cache: sbt
+
+      - name: sbt update
+        if: matrix.java == 'corretto@11' && steps.setup-java-corretto-11.outputs.cache-hit == 'false'
+        run: sbt +update
+
+      - name: Setup Java (corretto@17)
+        id: setup-java-corretto-17
+        if: matrix.java == 'corretto@17'
+        uses: actions/setup-java@v4
+        with:
+          distribution: corretto
+          java-version: 17
+          cache: sbt
+
+      - name: sbt update
+        if: matrix.java == 'corretto@17' && steps.setup-java-corretto-17.outputs.cache-hit == 'false'
+        run: sbt +update
+
+      - name: Generate site
+        run: sbt docs/tlSite
+
+      - name: Publish site
+        if: github.event_name != 'pull_request' && startsWith(github.ref, 'refs/tags/v')
+        uses: peaceiris/actions-gh-pages@v4.0.0
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/target/docs/site
+          keep_files: false
+
   sbtScripted:
     name: sbt scripted
     strategy:

.gitignore

@@ -13,3 +13,6 @@ metals.sbt
 
 **/benchmark/**/*.json
 **/benchmark/**/*.svg
+
+# for Scala CLI
+**/.scala-build/

CONTRIBUTING.md

@@ -4,7 +4,7 @@ These guidelines are meant to be a living document that should be changed and ad
 
 ## Tooling
 
-LDBC is built with [sbt](https://github.com/sbt/sbt), and you should be able to jump right in by running `sbt test`.
+ldbc is built with [sbt](https://github.com/sbt/sbt), and you should be able to jump right in by running `sbt test`.
 
 Please make sure to run `sbt scalafmtAll` (and commit the results!) before opening a pull request. This will take care of running both scalafmt, ensuring that the build doesn't just immediately fail to compile your work.
 

README.md

@@ -16,15 +16,18 @@
 
 ldbc (Lepus Database Connectivity) is Pure functional JDBC layer with Cats Effect 3 and Scala 3.
 
-ldbc is Created under the influence of [tapir](https://github.com/softwaremill/tapir), a declarative, type-safe web endpoint library. Using tapir, you can build type-safe endpoints and also generate OpenAPI documentation from the endpoints you build.
+ldbc is a [Typelevel](http://typelevel.org/) project. This means we embrace pure, typeful, functional programming, and provide a safe and friendly environment for teaching, learning, and contributing as described in the Scala [Code of Conduct](http://scala-lang.org/conduct.html).
 
-ldbc allows the same type-safe construction with Scala at the database layer and document generation using the constructed one.
+Note that **ldbc** is pre-1.0 software and is still undergoing active development. New versions are **not** binary compatible with prior versions, although in most cases user code will be source compatible.
 
 > [!NOTE]
 > **ldbc** is pre-1.0 software and is still undergoing active development. New versions are **not** binary compatible with prior versions, although in most cases user code will be source compatible.
 
 Please drop a :star: if this project interests you. I need encouragement.
 
+> [!CAUTION]
+> The current README contains the contents of the `0.3.x` version under development. Please refer to the [documentation](https://takapi327.github.io/ldbc/0.2) for the `0.2.x` version, which is currently released as a stable version.
+
 ## Modules availability
 
 ldbc is available on the JVM, Scala.js, and ScalaNative
@@ -50,33 +53,33 @@ For people that want to skip the explanations and see it action, this is the pla
 ### Dependency Configuration
 
 ```scala
-libraryDependencies += "io.github.takapi327" %% "ldbc-dsl" % "${version}"
+libraryDependencies += "io.github.takapi327" %% "ldbc-dsl" % "latest"
 ```
 
 For Cross-Platform projects (JVM, JS, and/or Native):
 
 ```scala
-libraryDependencies += "io.github.takapi327" %%% "ldbc-dsl" % "${version}"
+libraryDependencies += "io.github.takapi327" %%% "ldbc-dsl" % "latest"
 ```
 
 The dependency package used depends on whether the database connection is made via a connector using the Java API or a connector provided by ldbc.
 
 **Use jdbc connector**
 
 ```scala
-libraryDependencies += "io.github.takapi327" %% "jdbc-connector" % "${version}"
+libraryDependencies += "io.github.takapi327" %% "jdbc-connector" % "latest"
 ```
 
 **Use ldbc connector**
 
 ```scala
-libraryDependencies += "io.github.takapi327" %% "ldbc-connector" % "${version}"
+libraryDependencies += "io.github.takapi327" %% "ldbc-connector" % "latest"
 ```
 
 For Cross-Platform projects (JVM, JS, and/or Native)
 
 ```scala
-libraryDependencies += "io.github.takapi327" %%% "ldbc-connector" % "${version}"
+libraryDependencies += "io.github.takapi327" %%% "ldbc-connector" % "latest"
 ```
 
 ### Usage
@@ -118,7 +121,7 @@ val connection: Resource[IO, Connection[IO]] =
 
 The connection process to the database can be carried out using the connections established by each of these methods.
 
-```scala
+```scala 3
 val result: IO[(List[Int], Option[Int], Int)] = connection.use { conn =>
   (for
     result1 <- sql"SELECT 1".query[Int].to[List]
@@ -135,13 +138,13 @@ ldbc provides not only plain queries but also type-safe database connections usi
 The first step is to set up dependencies.
 
 ```scala
-libraryDependencies += "io.github.takapi327" %% "ldbc-query-builder" % "${version}"
+libraryDependencies += "io.github.takapi327" %% "ldbc-query-builder" % "latest"
 ```
 
 For Cross-Platform projects (JVM, JS, and/or Native):
 
 ```scala
-libraryDependencies += "io.github.takapi327" %%% "ldbc-query-builder" % "${version}"
+libraryDependencies += "io.github.takapi327" %%% "ldbc-query-builder" % "latest"
 ```
 
 ldbc uses classes to construct queries.
@@ -180,13 +183,13 @@ ldbc also allows type-safe construction of schema information for tables.
 The first step is to set up dependencies.
 
 ```scala
-libraryDependencies += "io.github.takapi327" %% "ldbc-schema" % "${version}"
+libraryDependencies += "io.github.takapi327" %% "ldbc-schema" % "latest"
 ```
 
 For Cross-Platform projects (JVM, JS, and/or Native):
 
 ```scala
-libraryDependencies += "io.github.takapi327" %%% "ldbc-schema" % "${version}"
+libraryDependencies += "io.github.takapi327" %%% "ldbc-schema" % "latest"
 ```
 
 The next step is to create a schema for use by the query builder.
@@ -222,8 +225,8 @@ val result: IO[List[User]] = connection.use { conn =>
 
 Full documentation can be found at Currently available in English and Japanese.
 
-- [English](https://takapi327.github.io/ldbc/en/index.html)
-- [Japanese](https://takapi327.github.io/ldbc/ja/index.html)
+- [English](https://takapi327.github.io/ldbc/0.2/en/)
+- [Japanese](https://takapi327.github.io/ldbc/0.2/ja/)
 
 ## Features/Roadmap
 

build.sbt

@@ -12,7 +12,7 @@ import Workflows.*
 import ProjectKeys.*
 import Implicits.*
 
-ThisBuild / tlBaseVersion              := "0.3"
+ThisBuild / tlBaseVersion              := LdbcVersions.latest
 ThisBuild / tlFatalWarnings            := true
 ThisBuild / projectName                := "ldbc"
 ThisBuild / scalaVersion               := scala3
@@ -24,6 +24,8 @@ ThisBuild / githubWorkflowAddedJobs ++= Seq(sbtScripted.value)
 ThisBuild / githubWorkflowBuildPostamble += dockerStop
 ThisBuild / githubWorkflowTargetBranches        := Seq("**")
 ThisBuild / githubWorkflowPublishTargetBranches := Seq(RefPredicate.StartsWith(Ref.Tag("v")))
+ThisBuild / tlSitePublishBranch                 := None
+ThisBuild / tlSiteKeepFiles                     := false // TODO: Deleted when publishing documentation for 0.3
 
 ThisBuild / sonatypeCredentialHost := "s01.oss.sonatype.org"
 sonatypeRepository                 := "https://s01.oss.sonatype.org/service/local"
@@ -216,34 +218,22 @@ lazy val benchmark = (project in file("benchmark"))
 
 lazy val docs = (project in file("docs"))
   .settings(
-    description   := "Documentation for ldbc",
-    scalacOptions := Nil,
-    mdocIn        := baseDirectory.value / "src" / "main" / "mdoc",
-    paradoxTheme  := Some(builtinParadoxTheme("generic")),
-    paradoxProperties ++= Map(
-      "org"          -> organization.value,
-      "scalaVersion" -> scalaVersion.value,
-      "version"      -> version.value.takeWhile(_ != '+'),
-      "mysqlVersion" -> mysqlVersion
+    description              := "Documentation for ldbc",
+    mdocIn                   := (Compile / sourceDirectory).value / "mdoc",
+    tlSiteIsTypelevelProject := Some(TypelevelProject.Affiliate),
+    mdocVariables ++= Map(
+      "ORGANIZATION"  -> organization.value,
+      "SCALA_VERSION" -> scalaVersion.value,
+      "MYSQL_VERSION" -> mysqlVersion
     ),
-    Compile / paradox / sourceDirectory := mdocOut.value,
-    Compile / paradoxRoots              := List("index.html", "en/index.html", "ja/index.html"),
-    makeSite                            := makeSite.dependsOn(mdoc.toTask("")).value,
-    git.remoteRepo                      := "git@github.com:takapi327/ldbc.git",
-    ghpagesNoJekyll                     := true
+    laikaTheme := LaikaSettings.helium.value
   )
   .settings(commonSettings)
   .dependsOn(
-    core.jvm,
-    sql.jvm,
-    dsl.jvm,
-    queryBuilder.jvm,
-    schema.jvm,
-    schemaSpy,
-    codegen.jvm,
-    hikari
+    connector.jvm,
+    schema.jvm
   )
-  .enablePlugins(MdocPlugin, SitePreviewPlugin, ParadoxSitePlugin, GhpagesPlugin, NoPublishPlugin)
+  .enablePlugins(AutomateHeaderPlugin, TypelevelSitePlugin, NoPublishPlugin)
 
 lazy val ldbc = tlCrossRootProject
   .settings(description := "Pure functional JDBC layer with Cats Effect 3 and Scala 3")

docs/src/main/mdoc/README.md

@@ -0,0 +1,47 @@
+{%
+laika.title = ldbc
+laika.versioned = false
+laika.metadata {
+language = en
+isRootPath = true
+}
+%}
+
+# ldbc (Lepus Database Connectivity)
+
+@:image(img/lepus_logo.png) {
+alt = "ldbc (Lepus Database Connectivity)"
+style = "center-logo"
+}
+
+[![Maven Central Version](https://img.shields.io/maven-central/v/io.github.takapi327/ldbc-core_3?color=blue)](https://search.maven.org/artifact/io.github.takapi327/ldbc-core_3/0.2.1/jar)
+[![MIT License](https://img.shields.io/badge/license-MIT-green)](https://en.wikipedia.org/wiki/MIT_License)
+[![Scala Version](https://img.shields.io/badge/scala-v3.3.x-red)](https://github.com/lampepfl/dotty)
+[![Typelevel Affiliate Project](https://img.shields.io/badge/typelevel-affiliate%20project-FF6169.svg)](https://typelevel.org/projects/affiliate/)
+
+ldbc (Lepus Database Connectivity) is Pure functional JDBC layer with Cats Effect 3 and Scala 3.
+
+ldbc is Created under the influence of [tapir](https://github.com/softwaremill/tapir), a declarative, type-safe web endpoint library. Using tapir, you can build type-safe endpoints and also generate OpenAPI documentation from the endpoints you build.
+
+ldbc allows the same type-safe construction with Scala at the database layer and document generation using the constructed one.
+
+Note that **ldbc** is pre-1.0 software and is still undergoing active development. New versions are **not** binary compatible with prior versions, although in most cases user code will be source compatible.
+
+## Documentation
+
+Full documentation can be found at Currently available in English and Japanese.
+
+- [English](en/index.md)
+- [Japanese](ja/index.md)
+
+## Contributing
+
+All suggestions welcome :)!
+
+If you’d like to contribute, see the list of [issues](https://github.com/takapi327/ldbc/issues) and pick one! Or report your own. If you have an idea you’d like to discuss, that’s always a good option.
+
+If you have any questions about why or how it works, feel free to ask on github. This probably means that the documentation, scaladocs, and code are unclear and can be improved for the benefit of all.
+
+### Testing locally
+
+If you want to build and run the tests for yourself, you'll need a local MySQL database. The easiest way to do this is to run `docker-compose up` from the project root.

docs/src/main/mdoc/css/site.css

@@ -0,0 +1,7 @@
+.center-logo {
+  text-align: center;
+}
+
+table td:not(:has(code)) {
+  text-align: center;
+}

docs/src/main/mdoc/default.template.html

@@ -0,0 +1,50 @@
+<!DOCTYPE html>
+<html lang="${?laika.metadata.language}">
+
+@:include(helium.site.templates.head)
+
+<body>
+
+@:include(helium.site.templates.topNav)
+
+<nav id="sidebar">
+
+  <div class="row">
+    @:for(helium.site.topNavigation.phoneLinks)
+    ${_}
+    @:@
+  </div>
+
+  @:if(laika.metadata.isRootPath)
+  @:navigationTree {
+    entries = ${helium.site.mainNavigation.prependLinks} [
+      { target = "/", excludeRoot = true, depth = 1 }
+    ] ${helium.site.mainNavigation.appendLinks}
+  }
+  @:else
+  @:navigationTree {
+    entries = ${helium.site.mainNavigation.prependLinks} [
+      { target = /${laika.metadata.language}/, excludeRoot = true, excludeSections = ${helium.site.mainNavigation.excludeSections}, depth = ${helium.site.mainNavigation.depth} },
+    ] ${helium.site.mainNavigation.appendLinks}
+  }
+  @:@
+
+</nav>
+
+<div id="container">
+
+  @:include(helium.site.templates.pageNav)
+
+  <main class="content">
+
+    ${cursor.currentDocument.content}
+
+    @:include(helium.site.templates.footer)
+
+  </main>
+
+</div>
+
+</body>
+
+</html>

docs/src/main/mdoc/directory.conf

@@ -0,0 +1,5 @@
+laika.navigationOrder = [
+  index.md
+  older-versions.md
+]
+laika.versioned = true