Add mdoc for README generation

README.md

@@ -3,10 +3,41 @@ A referentially transparent FFI to `org.apache.avro.SchemaBuilder`
 
 ### Welcome to `schemabuilder4cats`
 
-##### Add the dependency:
+Let's build schemas secure in the knowledge that we won't be causing side-effects.
 
-    "com.julianpeeters" %% "schemabuilder4cats" % "0.1.0-SNAPSHOT"
+##### Add the dependency
 
-### `schemabuilder4cats` Essentials
+```
+"com.julianpeeters" %% "schemabuilder4cats" % "0.1.0-SNAPSHOT"
+```
 
-The `SchemaBuilder` API is modelled after `org.apache.avro.SchemaBuilder` ([Javadoc](https://avro.apache.org/docs/1.11.1/api/java/)).
+### Usage
+
+The `SchemaBuilder` API is modelled after `org.apache.avro.SchemaBuilder`.
+Please see the corresponding Apache Avro Java 1.11.1 API
+[Javadoc](https://avro.apache.org/docs/1.11.1/api/java/) for documentation.
+
+##### Example:
+
+```scala
+import cats.effect.IO
+import org.apache.avro.Schema
+import schemabuilder4cats.SchemaBuilder
+
+// define B as a contextual abstraction in order to import extension methodss
+given B: SchemaBuilder[IO] = SchemaBuilder[IO]
+val record: IO[Schema] = B.record("myrecord").fields.endRecord
+```
+
+##### Result:
+```scala
+import cats.effect.unsafe.implicits.global
+
+// example usage only, avoid unsafe methods in real code
+record.unsafeRunSync().toString(true)
+// res0: String = """{
+//   "type" : "record",
+//   "name" : "myrecord",
+//   "fields" : [ ]
+// }"""
+```

build.sbt

@@ -30,4 +30,15 @@ lazy val schemabuilder4cats = (project in file("."))
       // test
       "org.typelevel" %% "munit-cats-effect-3" % MUnitCEV % Test,
     )
-  )
+  )
+
+lazy val docs = project.in(file("docs/gitignored"))
+  .settings(
+    mdocOut := schemabuilder4cats.base,
+    mdocVariables := Map(
+      "AVRO" -> ApacheAvroV,
+      "VERSION" -> version.value
+    )
+  )
+  .dependsOn(schemabuilder4cats)
+  .enablePlugins(MdocPlugin)

docs/readme.md

@@ -0,0 +1,38 @@
+# schemabuilder4cats
+A referentially transparent FFI to `org.apache.avro.SchemaBuilder`
+
+### Welcome to `schemabuilder4cats`
+
+Let's build schemas secure in the knowledge that we won't be causing side-effects.
+
+##### Add the dependency
+
+```
+"com.julianpeeters" %% "schemabuilder4cats" % "@VERSION@"
+```
+
+### Usage
+
+The `SchemaBuilder` API is modelled after `org.apache.avro.SchemaBuilder`.
+Please see the corresponding Apache Avro Java @AVRO@ API
+[Javadoc](https://avro.apache.org/docs/@AVRO@/api/java/) for documentation.
+
+##### Example:
+
+```scala mdoc:silent
+import cats.effect.IO
+import org.apache.avro.Schema
+import schemabuilder4cats.SchemaBuilder
+
+// define B as a contextual abstraction in order to import extension methodss
+given B: SchemaBuilder[IO] = SchemaBuilder[IO]
+val record: IO[Schema] = B.record("myrecord").fields.endRecord
+```
+
+##### Result:
+```scala mdoc
+import cats.effect.unsafe.implicits.global
+
+// example usage only, avoid unsafe methods in real code
+record.unsafeRunSync().toString(true)
+```

project/plugins.sbt

@@ -0,0 +1 @@
+addSbtPlugin("org.scalameta" % "sbt-mdoc" % "2.3.7" )