Adding readme code snippets to testing suits.

urosjarc · Mar 31, 2024 · d42e57e · d42e57e
1 parent d100f10
commit d42e57e
Show file tree

Hide file tree

Showing 5 changed files with 416 additions and 36 deletions.
diff --git a/.github/workflows/publish-gh-pages.yml b/.github/workflows/publish-gh-pages.yml
@@ -0,0 +1,30 @@
+name: Docs for db-messiah-extra
+
+on:
+  push:
+
+permissions:
+  contents: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Set up JDK 19
+        uses: actions/setup-java@v4
+        with:
+          java-version: 19
+          distribution: 'adopt'
+
+      - name: Build documentation
+        run: ./gradlew dokkaHtml
+
+      - name: Publish documentation
+        uses: JamesIves/github-pages-deploy-action@releases/v4
+        with:
+          BRANCH: gh-pages
+          FOLDER: build/dokka/html
diff --git a/README.md b/README.md
@@ -1,14 +1,27 @@
 <h1 align="center">db-messiah-extra</h1>
 <h3 align="center">Extra Utils for Db Messiah, kotlin lib. for enterprise database development</h3>
+<p align="center">
+    readme code snippets are
+    <a href="https://github.com/urosjarc/db-messiah/blob/master/src/tutorials/kotlin/Test_README.md">autogenerated</a>
+    and
+    <a href="https://github.com/urosjarc/db-messiah/blob/master/src/tutorials/kotlin/Test_README.kt">tested</a><br>
+    +<b>15</b> <a href="https://github.com/urosjarc/db-messiah/blob/master/src/e2e">e2e</a> tests with <b>100%</b> instruction coverage
+</p>
 <br>
 <br>
 <table width="100%" border="0">
     <tr>
-        <td width="50%">
+        <td width="33%">
             <h3 align="center"><a href="https://github.com/urosjarc/db-messiah">db-messiah</a></h3>
             <p align="center">Kotlin lib. for enterprise database development</p>
         </td>
-        <td width="50%">
+        <td width="33%" align="center">
+                <p><a href="#get-started">Get started</a></p>
+                <p><a href="#specifications">Specifications</a></p>
+                <p><a href="#arhitecture">Arhitecture</a></p>
+                <p><a href="https://urosjarc.github.io/db-messiah-extra/">Documentation</a></p>
+        </td>
+        <td width="33%">
             <h3 align="center"><a href="https://github.com/urosjarc/db-analyser">db-analyser</a></h3>
             <p align="center">GUI for db analysis, to help you create complex JOIN statements for SQL or db-messiah.
         </td>
@@ -20,66 +33,129 @@
 <h2 align="center">Get started</h2>
 
 ```kotlin
-implementation("com.urosjarc:db-messiah-extra:0.0.1")
+implementation("com.urosjarc:db-messiah-extra-extra:0.0.1")
 ```
 
-<br><h3 align="center">DB Serializers</h3>
+<br><h3 align="center">Domain</h3>
 
 ```kotlin
-/** SQLITE */
-
-val sqliteSerializer = SqliteSerializer(
-    globalSerializers = BasicTS.sqlite + KotlinxTimeTS.sqlite,
-    ...
+@Serializable
+data class MyTable(
+    @Contextual
+    val pk: UUID = UUID.randomUUID(),
+    val instant: kotlinx.datetime.Instant,
+    val localDate: kotlinx.datetime.LocalDate,
+    val localTime: kotlinx.datetime.LocalTime,
 )
 
-/** POSTGRESQL */
+```
 
+<br><h3 align="center">DB Serializers</h3>
+
+```kotlin
 val sqliteSerializer = SqliteSerializer(
     globalSerializers = BasicTS.sqlite + KotlinxTimeTS.sqlite,
-    ...
+    tables = listOf(Table(MyTable::pk)),
 )
 ```
 
 <br><h3 align="center">JSON Serializers</h3>
 
-
 ```kotlin
 /** JSON */
 
 val json = Json {
-        serializersModule = SerializersModule {
+    serializersModule = SerializersModule {
         contextual(InstantJS)
         contextual(LocalDateJS)
         contextual(LocalTimeJS)
         contextual(UUIDJS)
     }
 }
 
-val jsonStr = json.encodeToString(...)
-val obj = json.decodeFromString<...>(...)
-
-/** KTOR */
 
-install(ContentNegotiation) {
-    json(Json {
-        serializersModule = SerializersModule {
-            contextual(InstantJS)
-            contextual(LocalDateJS)
-            contextual(LocalTimeJS)
-            contextual(UUIDJS)
-        }
-    })
+val dtNow = Clock.System.now().toLocalDateTime(timeZone = TimeZone.UTC)
+val myTable = MyTable(
+    instant = Clock.System.now(),
+    localDate = dtNow.date,
+    localTime = dtNow.time
+)
+
+val jsonStr = json.encodeToString(myTable)
+val obj = json.decodeFromString<MyTable>(jsonStr)
+assert(obj == myTable)
+
+/** KTOR */
+embeddedServer(Netty, port = 8080, host = "0.0.0.0") {
+    install(ContentNegotiation) {
+        json(Json {
+            serializersModule = SerializersModule {
+                contextual(InstantJS)
+                contextual(LocalDateJS)
+                contextual(LocalTimeJS)
+                contextual(UUIDJS)
+            }
+        })
+    }
 }
 ```
 
-<br><h3 align="center">Features</h3>
+<br><br><h2 align="center">Specifications</h3>
+
+|     Class     |    COLUMN    |              Databases               |      db-messiah-extra       |    JSON     |
+|:-------------:|:------------:|:------------------------------------:|:---------------------------:|:-----------:|
+|    Instant    |   DATETIME   | Sqlite, Mysql, MSSql, Maria, H2, DB2 | KotlinxInstantTS. DATETIME  |  InstantJS  |
+|    Instant    |  TIMESTAMP   |       Derby, Postgres, Oracle        | KotlinxInstantTS. TIMESTAMP |  InstantJS  |
+| LocalDateTime |     :x:      |                 :x:                  |             :x:             |     :x:     |
+|   LocalDate   |     DATE     |          :white_check_mark:          |  KotlinxLocalDateTS. DATE   | LocalDateJS |
+|   LocalTime   |     TIME     |    :white_check_mark: but Oracle     |     KotlinxTimeTS.TIME      | LocalDateJS |
+|   LocalTime   | NUMBER(8, 0) |                Oracle                |   KotlinxTimeTS. NUMBER8    | LocalTimeJS |
+|     UUID      |  db-messiah  |              db-messiah              |         db-messiah          |   UUIDJS    |
 
-|   Class   |    COLUMN    |              Databases               |      db-messiah-extra       |    JSON     |
-|:---------:|:------------:|:------------------------------------:|:---------------------------:|:-----------:|
-|  Instant  |   DATETIME   | Sqlite, Mysql, MSSql, Maria, H2, DB2 | KotlinxInstantTS. DATETIME  |  InstantJS  |
-|  Instant  |  TIMESTAMP   |       Derby, Postgres, Oracle        | KotlinxInstantTS. TIMESTAMP |  InstantJS  |
-| LocalDate |     DATE     |          :white_check_mark:          |  KotlinxLocalDateTS. DATE   | LocalDateJS |
-| LocalTime |     TIME     |    :white_check_mark: but Oracle     |     KotlinxTimeTS.TIME      | LocalDateJS |
-| LocalTime | NUMBER(8, 0) |                Oracle                |   KotlinxTimeTS. NUMBER8    | LocalTimeJS |>
-|   UUID    |  db-messiah  |              db-messiah              |         db-messiah          |   UUIDJS    |>
+<br><br><h2 align="center">Arhitecture</h3>
+
+```text
+src/main/kotlin/com/urosjarc/dbmessiah/extra/
+|-- kotlinx
+|   |-- InstantJS.kt............| java.time.Instant serializer for kotlinx.serialization
+|   |-- LocalDateJS.kt..........| java.time.LocalDate serializer for kotlinx.serialization
+|   |-- LocalTimeJS.kt..........| java.time.LocalTime serializer for kotlinx.serialization
+|   `-- UUIDJS.kt...............| java.utils.UUID serializer for kotlinx.serialization
+`-- serializers
+    |-- KotlinxInstantTS.kt.....| kotlinx.datetime.Instant type serializer for db-messiah
+    |-- KotlinxLocalDateTS.kt...| kotlinx.datetime.LocalDate type serializer for db-messiah
+    |-- KotlinxLocalTimeTS.kt...| kotlinx.datetime.LocalTime type serializer for db-messiah
+    `-- KotlinxTimeTS.kt........| kotlinx.datetime.Time type serializer for db-messiah
+```
+
+<br><br><h2 align="center">Sources</h2>
+
+```text
+src/
+|-- main...............................| Already described in architecture.
+`-- test
+    |-- kotlin
+    |   |-- impl
+    |   |   |-- Test_Contract.kt.......| Testing interface for all db tests.
+    |   |   |-- Test_Db2.kt
+    |   |   |-- Test_Derby.kt
+    |   |   |-- Test_H2.kt
+    |   |   |-- Test_Maria.kt
+    |   |   |-- Test_Mssql.kt
+    |   |   |-- Test_Mysql.kt
+    |   |   |-- Test_Oracle.kt
+    |   |   |-- Test_Postgresql.kt
+    |   |   `-- Test_Sqlite.kt
+    |   |-- Test_InstantJS.kt
+    |   |-- Test_LocalDateJS.kt
+    |   |-- Test_LocalTimeJS.kt
+    |   |-- Test_README.kt.............| Code from where README.md is generated.
+    |   |-- Test_README.md.............| Template from where README.md is generated.
+    |   |-- Test_UUIDJS.kt
+    |   `-- utils
+    |       |-- domain.kt
+    |       |-- Schemas.kt
+    |       `-- Serializers.kt
+    `-- resources
+        `-- log4j2.xml
+```
diff --git a/build.gradle.kts b/build.gradle.kts
@@ -1,6 +1,5 @@
 import org.jetbrains.dokka.DokkaConfiguration.Visibility
 import java.lang.Thread.sleep
-import java.net.URI
 
 val GPG_PRIVATE_KEY = System.getenv("GPG_PRIVATE_KEY")
 val GPG_PRIVATE_PASSWORD = System.getenv("GPG_PRIVATE_PASSWORD")
@@ -111,6 +110,12 @@ dependencies {
     testImplementation("org.apache.logging.log4j:log4j-slf4j2-impl:2.20.0")
     testImplementation("org.jetbrains.kotlin:kotlin-test")
     testImplementation("com.urosjarc:db-messiah:$dbMessiah")
+
+    val ktor_version = "2.3.8"
+    testImplementation("io.ktor:ktor-server-core-jvm:$ktor_version")
+    testImplementation("io.ktor:ktor-server-netty-jvm:$ktor_version")
+    testImplementation("io.ktor:ktor-server-content-negotiation:$ktor_version")
+    testImplementation("io.ktor:ktor-serialization-kotlinx-json:$ktor_version")
 }
 
 tasks.test {
@@ -166,3 +171,43 @@ publishing {
     }
 
 }
+
+tasks.register<GradleBuild>("readme") {
+    group = "verification"
+    description = "Create README.md tests."
+    this.tasks = listOf("test")
+
+    doLast {
+        val templateLines = File("./src/test/kotlin/Test_README.kt").readLines()
+        var readme = File("./src/test/kotlin/Test_README.md").readText()
+
+        val dependencies = mutableListOf(
+            "implementation(\"${project.group}:${project.name}-extra:$version\")",
+        )
+
+        val readmeMap: MutableList<Pair<String, MutableList<String>>> = mutableListOf(
+            "// START 'Dependencies'" to dependencies,
+        )
+
+
+        var active = false
+        var indent = ""
+        templateLines.forEach {
+            if (it.contains("// START '")) {
+                indent = it.split("//").first()
+                active = true
+                readmeMap.add(it.replaceFirst(indent, "") to mutableListOf())
+            } else if (it.contains("// STOP")) {
+                active = false
+            } else if (active) {
+                readmeMap.last().second.add(it.replaceFirst(indent, ""))
+            }
+        }
+
+        readmeMap.forEach { (key, value) ->
+            readme = readme.replace(oldValue = key, newValue = value.joinToString("\n"))
+        }
+
+        File("README.md").writeText(readme)
+    }
+}