Merge pull request #14 from softinio/docs-and-release-improvements

documentation and release improvements including adding cats-effect docs

Author: softinio

.github/workflows/docs.yml

@@ -47,6 +47,7 @@ jobs:
     - name: Generate documentation
       run: |
         nix develop --command mill 'duck4s[3.8.2].docJar'
+        nix develop --command mill 'duck4s-cats-effect[3.8.2].docJar'
 
     # Deploy to gh-pages branch
     - name: Deploy to GitHub Pages
@@ -57,7 +58,9 @@ jobs:
 
         # Create temporary directory
         TEMP_DIR=$(mktemp -d)
-        cp -r out/duck4s/3.8.2/docJar.dest/javadoc/* "$TEMP_DIR/"
+        cp -r out/duck4s/3.8.2/docJar.dest/docs/* "$TEMP_DIR/"
+        mkdir -p "$TEMP_DIR/cats-effect-api"
+        cp -r out/duck4s-cats-effect/3.8.2/docJar.dest/docs/* "$TEMP_DIR/cats-effect-api/"
 
         # Check if gh-pages branch exists
         if git ls-remote --heads origin gh-pages | grep -q gh-pages; then

CLAUDE.md

@@ -25,7 +25,9 @@ This project supports multiple Scala versions: **3.3.6** and **3.8.2**
 
 #### Documentation Commands
 - **Generate API documentation with static site**: `mill 'duck4s[3.8.2].docJar'`
-- **Generated site location**: `out/duck4s/3.8.2/docJar.dest/javadoc/index.html`
+- **Generated site location**: `out/duck4s/3.8.2/docJar.dest/docs/index.html`
+- **Preview docs locally**: `scala-cli run scripts/preview-docs.scala` (generates both core and cats-effect docs, merges them, and serves at http://localhost:8080)
+  - Optional port: `scala-cli run scripts/preview-docs.scala -- --port 9000`
 
 #### Development Commands
 - **Format code**: `mill mill.scalalib.scalafmt.ScalafmtModule/reformatAll __.sources`

build.mill

@@ -122,6 +122,21 @@ trait Duck4sCatsEffectModule
       common :+ "-Xkind-projector:underscores"
     else common
 
+  def scalaDocOptions = Task {
+    val version = Task.env.get("DUCK4S_DOC_VERSION").getOrElse(publishVersion())
+    super.scalaDocOptions() ++ Seq(
+      "-project",
+      "Duck4s Cats Effect",
+      "-project-version",
+      version,
+      "-social-links:github::https://github.com/softinio/duck4s",
+      "-groups",
+      "-external-mappings:" +
+        ".*scala.*::scaladoc3::https://scala-lang.org/api/3.x/," +
+        ".*java.*::javadoc::https://docs.oracle.com/en/java/javase/17/docs/api/"
+    )
+  }
+
   def pomSettings = PomSettings(
     description = "Scala 3 cats-effect integration for duck4s DuckDB library",
     organization = "com.softinio",

devshell.toml

@@ -3,6 +3,16 @@
 [[commands]]
 package = "mill"
 
+[[commands]]
+name = "fmt"
+command = "mill mill.scalalib.scalafmt.ScalafmtModule/reformatAll __.sources"
+help = "Format all source files with Scalafmt"
+
+[[commands]]
+name = "preview-docs"
+command = "scala-cli run scripts/preview-docs.scala"
+help = "Preview the documentation site locally"
+
 [devshell]
 packages = [
   "coursier",

duck4s-cats-effect/src/DuckDBException.scala

@@ -34,12 +34,13 @@ class DuckDBException(
     cause: Option[Throwable] = None
 ) extends RuntimeException(message, cause.orNull)
 
-/** Factory methods for creating [[DuckDBException]] from [[DuckDBError]]
-  * values.
+/** Factory methods for creating [[DuckDBException]] from
+  * [[com.softinio.duck4s.algebra.DuckDBError]] values.
   */
 object DuckDBException:
 
-  /** Converts a [[DuckDBError]] into a [[DuckDBException]].
+  /** Converts a [[com.softinio.duck4s.algebra.DuckDBError]] into a
+    * [[DuckDBException]].
     *
     * @param error
     *   The DuckDBError to wrap

duck4s-cats-effect/src/DuckDBIO.scala

@@ -49,13 +49,13 @@ object DuckDBIO:
   private[effect] def liftE[T](e: Either[DuckDBError, T]): IO[T] =
     IO.fromEither(e.left.map(DuckDBException.from))
 
-  /** Acquires a DuckDB connection as a cats-effect [[Resource]]. The connection
-    * is closed automatically on release.
+  /** Acquires a DuckDB connection as a cats-effect [[cats.effect.Resource]].
+    * The connection is closed automatically on release.
     *
     * @param config
     *   Database configuration. Defaults to in-memory mode.
     * @return
-    *   A [[Resource]] that manages the connection lifecycle.
+    *   A [[cats.effect.Resource]] that manages the connection lifecycle.
     */
   def connect(
       config: DuckDBConfig = DuckDBConfig.inMemory

duck4s/docs/_docs/cats-effect.md

@@ -299,6 +299,7 @@ object Main extends IOApp.Simple:
 ## Next Steps
 
 - [Getting Started](getting-started.html) - Core synchronous API
-- [API Documentation](../index.html) - Complete API reference
+- [Core API Documentation](../index.html) - Core API reference
+- [Cats-Effect API Documentation](../cats-effect-api/index.html) - Cats-effect module API reference
 - [cats-effect documentation](https://typelevel.org/cats-effect/)
 - [fs2 documentation](https://fs2.io/)

duck4s/docs/_docs/index.md

@@ -1,6 +1,3 @@
----
-title: Home
----
 
 ![](images/duck4s_logo.jpeg)
 
@@ -42,4 +39,5 @@ val result = DuckDBConnection.withConnection() { conn =>
 
 - [Getting Started](getting-started.html) - Learn the basics of duck4s
 - [Cats-Effect Integration](cats-effect.html) - Effectful IO and streaming with cats-effect and fs2
-- [API Documentation](../index.html) - Complete API reference
+- [API Documentation](../index.html) - Complete core API reference
+- [Cats-Effect API Documentation](../cats-effect-api/index.html) - Cats-effect module API reference

scripts/preview-docs.scala

@@ -0,0 +1,66 @@
+//> using scala "3.8.2"
+//> using dep "com.lihaoyi::cask:0.11.3"
+//> using dep "com.lihaoyi::os-lib:0.11.8"
+//> using mainClass "DocServer"
+
+/** Generates both doc sites and serves them locally for preview.
+  *
+  * Usage (from project root):
+  *   scala-cli run scripts/preview-docs.scala
+  *   scala-cli run scripts/preview-docs.scala -- --port 9000
+  */
+
+object DocServer extends cask.MainRoutes:
+  private var docsDir: String = ""
+  private var portNum: Int    = 8080
+
+  override def port      = portNum
+  override def host      = "localhost"
+  override def debugMode = false
+
+  @cask.staticFiles("/")
+  def staticFiles() = docsDir
+
+  initialize()
+
+  override def main(args: Array[String]): Unit =
+    portNum = args.zipWithIndex
+      .find(_._1 == "--port")
+      .flatMap { case (_, i) => args.lift(i + 1).flatMap(_.toIntOption) }
+      .getOrElse(8080)
+
+    val projectRoot = os.pwd
+
+    println("Generating core documentation...")
+    os.proc("mill", "duck4s[3.8.2].docJar")
+      .call(cwd = projectRoot, stdout = os.Inherit, stderr = os.Inherit)
+
+    println("Generating cats-effect documentation...")
+    os.proc("mill", "duck4s-cats-effect[3.8.2].docJar")
+      .call(cwd = projectRoot, stdout = os.Inherit, stderr = os.Inherit)
+
+    val coreDocsDir = projectRoot / "out" / "duck4s" / "3.8.2" / "docJar.dest" / "docs"
+    val catsDocsDir =
+      projectRoot / "out" / "duck4s-cats-effect" / "3.8.2" / "docJar.dest" / "docs"
+
+    val previewDir = os.temp.dir(prefix = "duck4s-preview")
+    println(s"Merging docs into $previewDir...")
+
+    // Copy core docs into preview root
+    os.list(coreDocsDir).foreach(p =>
+      os.copy(p, previewDir / p.last, replaceExisting = true, mergeFolders = true)
+    )
+
+    // Copy cats-effect docs into cats-effect-api/ subdirectory
+    val catsEffectOut = previewDir / "cats-effect-api"
+    os.makeDir.all(catsEffectOut)
+    os.list(catsDocsDir).foreach(p =>
+      os.copy(p, catsEffectOut / p.last, replaceExisting = true, mergeFolders = true)
+    )
+
+    docsDir = previewDir.toString
+
+    println(s"Docs ready. Open http://localhost:$portNum/index.html in your browser.")
+    println("Press Ctrl+C to stop.\n")
+
+    super.main(args)

scripts/publish-docs.sh

@@ -51,20 +51,28 @@ fi
 
 # Generate documentation
 echo "Generating documentation with version $VERSION..."
-DUCK4S_DOC_VERSION="$VERSION" nix develop --command mill 'duck4s[3.7.0].docJar'
+DUCK4S_DOC_VERSION="$VERSION" nix develop --command mill 'duck4s[3.8.2].docJar'
+DUCK4S_DOC_VERSION="$VERSION" nix develop --command mill 'duck4s-cats-effect[3.8.2].docJar'
 
 # Check if documentation was generated
-if [ ! -d "out/duck4s/3.7.0/docJar.dest/javadoc" ]; then
+if [ ! -d "out/duck4s/3.8.2/docJar.dest/docs" ]; then
     echo "Error: Documentation generation failed"
     exit 1
 fi
 
+if [ ! -d "out/duck4s-cats-effect/3.8.2/docJar.dest/docs" ]; then
+    echo "Error: Cats-effect documentation generation failed"
+    exit 1
+fi
+
 # Create temporary directory for docs
 TEMP_DIR=$(mktemp -d)
 echo "Preparing documentation in $TEMP_DIR..."
 
 # Copy documentation to temp directory
-cp -r out/duck4s/3.7.0/docJar.dest/javadoc/* "$TEMP_DIR/"
+cp -r out/duck4s/3.8.2/docJar.dest/docs/* "$TEMP_DIR/"
+mkdir -p "$TEMP_DIR/cats-effect-api"
+cp -r out/duck4s-cats-effect/3.8.2/docJar.dest/docs/* "$TEMP_DIR/cats-effect-api/"
 
 # Switch to gh-pages branch (create if doesn't exist)
 echo "Switching to gh-pages branch..."