docs: Reorganize structure and rewrite some pages

-Reorganize the structure of the docs according to newly decided structure.
-Rewrite these sections: Introduction, Getting Started, Working with Database, Working with Data Source, Working with Transaction, Asynchronous Support.

documentation-website/Writerside/hi.tree

@@ -8,11 +8,19 @@
 
     <toc-element topic="Default-topic.md"/>
     <toc-element topic="Introduction.md"/>
-    <toc-element topic="Getting-Started.md"/>
-    <toc-element topic="Database-and-DataSource.md"/>
-    <toc-element topic="Transactions.md"/>
-    <toc-element topic="DSL-API.md"/>
-    <toc-element topic="DAO-API.md"/>
+    <toc-element topic="Tutorials-and-Samples.md">
+        <toc-element topic="Getting-Started.md"/>
+        <toc-element topic="Samples.md"/>
+    </toc-element>
+    <toc-element topic="Databases.md">
+        <toc-element topic="Working-with-Database.md"/>
+        <toc-element topic="Working-with-DataSource.md"/>
+        <toc-element topic="Working-with-Transaction.md"/>
+    </toc-element>
+    <toc-element topic="Asynchronous-Support.md">
+    </toc-element>
+    <toc-element topic="Deep-Dive-into-DSL.md"/>
+    <toc-element topic="Deep-Dive-into-DAO.md"/>
     <toc-element topic="Modules-Documentation.md"/>
     <toc-element topic="Frequently-Asked-Questions.md"/>
     <toc-element topic="Migration-Guide.md"/>

documentation-website/Writerside/redirection-rules.xml

@@ -8,4 +8,37 @@
         <description>Created after removal of "Introduction" from Exposed Documentation</description>
         <accepts>Introduction.html</accepts>
     </rule>
+    <rule id="26523343">
+        <description>Created after removal of "Working with Database" from Exposed Documentation</description>
+        <accepts>Working-with-databases.html</accepts>
+    </rule>
+    <rule id="4bb974bd">
+        <description>Created after removal of "Working with DataSource" from Exposed Documentation</description>
+        <accepts>Working-with-data-sources.html</accepts>
+    </rule>
+    <rule id="2ce4908b">
+        <description>Created after removal of "Working with Transaction" from Exposed Documentation</description>
+        <accepts>Working-with-transactions.html</accepts>
+    </rule>
+    <rule id="66de3a7c">
+        <description><![CDATA[Created after removal of "<Samples-md.md>" from Exposed Documentation]]></description>
+        <accepts>Samples-md.html</accepts>
+    </rule>
+    <rule id="42666d4f">
+        <description>Created after removal of "Transactions" from Exposed Documentation</description>
+        <accepts>Transactions.html</accepts>
+    </rule>
+    <rule id="29b5804e">
+        <description>
+            <![CDATA[Created after removal of "<Working-with-Coroutines.md>" from Exposed Documentation]]></description>
+        <accepts>Working-with-Coroutines.html</accepts>
+    </rule>
+    <rule id="78f4505">
+        <description>Created after removal of "DAO API" from Exposed Documentation</description>
+        <accepts>DAO-API.html</accepts>
+    </rule>
+    <rule id="30ea6632">
+        <description>Created after removal of "DSL API" from Exposed Documentation</description>
+        <accepts>DSL-API.html</accepts>
+    </rule>
 </rules>

documentation-website/Writerside/topics/Asynchronous-Support.md

@@ -0,0 +1,60 @@
+# Asynchronous Support
+
+## Working with Coroutines
+
+In the modern world, non-blocking and asynchronous code is popular. Kotlin
+has [Coroutines](https://kotlinlang.org/docs/reference/coroutines-overview.html) that give you an imperative way of writing asynchronous code. Most
+Kotlin frameworks (like [ktor](https://ktor.io)) have built-in support for Coroutines while Exposed is mostly blocking. Why? Because Exposed uses JDBC API to interact
+with databases that was designed in an era of blocking APIs. Moreover, Exposed stores some values in
+thread-local variables while coroutines could (and will) be executed in different threads.
+
+Since Exposed 0.15.1, there are bridge functions that will give you a safe way to interact with Exposed within `suspend`
+blocks: `newSuspendedTransaction/Transaction.withSuspendTransaction` have the same parameters as a blocking `transaction` function but will allow you to
+provide a `CoroutineDispatcher` in which the function will be executed. If context is not provided, your code will be executed within the current `coroutineContext`.
+
+Sample usage looks like:
+
+```kotlin
+runBlocking {
+    transaction {
+        SchemaUtils.create(FooTable) // Table will be created on a current thread
+
+        newSuspendedTransaction(Dispatchers.Default) {
+            FooTable.insert { it[id] = 1 } // This insert will be executed in one of Default dispatcher threads
+
+            withSuspendTransaction {
+                val id = FooTable.select { FooTable.id eq 1 }
+                    .single()()[FooTable.id] // This select also will be executed on some thread from Default dispatcher using the same transaction
+            }
+        }
+
+        val result = newSuspendedTransaction(Dispatchers.IO) {
+            FooTable.select { FooTable.id eq 1 }
+                .single()[H2Tests.Testing.id] // This select will be executed on some thread from IO dispatcher using the same transaction
+        }
+    }
+}
+
+```  
+
+Please note that such code remains blocking (as it still uses JDBC) and you should not try to share a transaction between multiple threads as it will
+lead to undefined behaviour.
+
+If you want to execute some code asynchronously and use the result later in your code, take a look at `suspendedTransactionAsync` function.
+
+```kotlin
+val launchResult = suspendedTransactionAsync(Dispatchers.IO, db = db) {
+    FooTable.insert {}
+
+    FooTable.select { FooTable.id eq 1 }.singleOrNull()?.getOrNull(Testing.id)
+}
+
+println("Result: " + (launchResult.await() ?: - 1))
+
+```
+
+This function will accept the same parameters as `newSuspendedTransaction` above, but returns `Deferred` which you could call `await` on to achieve your
+result.
+
+`suspendedTransactionAsync` is always executed in a new transaction to prevent concurrency issues when queries execution order could be changed
+by `CoroutineDispatcher`.

documentation-website/Writerside/topics/Databases.md

@@ -0,0 +1,7 @@
+# Databases
+
+[Working with Database](Working-with-Database.md)
+
+[Working with DataSource](Working-with-DataSource.md)
+
+[Working with Transaction](Working-with-Transaction.md)

documentation-website/Writerside/topics/DAO-API.md → documentation-website/Writerside/topics/Deep-Dive-into-DAO.md

@@ -1,4 +1,4 @@
-# DAO API
+# Deep Dive into DAO
 
 ## Overview
 The DAO (Data Access Object) API of Exposed, is similar to ORM frameworks like Hibernate with a Kotlin-specific API.