Adjust main doc pages formatting and wording (sqldelight#4345)

Fix web-worker-driver doc page using `executeAs*()` methods.

docs/android_sqlite/index.md

@@ -1,9 +1,16 @@
-# Getting Started on Android
+# Getting Started with SQLite on Android
 
 {% include 'common/index_gradle_database.md' %}
 
+!!! tip
+    It's recommended to switch Android Studio to use the "Project" view instead of the "Android" 
+    view of your files, to make it easier to find and edit SQLDelight files.
+
 {% include 'common/index_schema.md' %}
 
+To use the generated database in your code, you must add the SQLDelight Android driver dependency to 
+your project.
+
 === "Kotlin"
     ```kotlin
     dependencies {
@@ -16,17 +23,23 @@
       implementation "app.cash.sqldelight:android-driver:{{ versions.sqldelight }}"
     }
     ```
+
+An instance of the driver can be constructed as shown below, and requires a reference to the generated `Schema` object.
 ```kotlin
 val driver: SqlDriver = AndroidSqliteDriver(Database.Schema, context, "test.db")
 ```
 
-It's recommended to switch Android Studio to use the "Project" view instead of the "Android" view of
-your files, in order to find and edit SQLDelight files.
+!!! info
+    The `AndroidSqliteDriver` will automatically create or migrate your schema when the driver is constructed.
+    Migrations can also be executed manually if needed. See [Code Migrations] for more
+
 
 {% include 'common/index_queries.md' %}
 
-## SQLite Version Support
+## SQLite Versions
 
-The SQLDelight Gradle plugin will automatically select the SQLite dialect version based on your project's 
-`minSdkVersion` setting. [See here](https://developer.android.com/reference/android/database/sqlite/package-summary) for 
+For Android projects, the SQLDelight Gradle plugin will automatically select the SQLite dialect 
+version based on your project's `minSdkVersion` setting. [See here](https://developer.android.com/reference/android/database/sqlite/package-summary) for 
 the list of supported SQLite versions on each Android SDK level.
+
+[Code Migrations]: migrations#code-migrations

docs/common/index_gradle_database.md

@@ -1,4 +1,4 @@
-First apply the gradle plugin in your project. {% if async %}Make sure to set `generateAsync` to 
+First apply the gradle plugin in your project{% if dialect %} and set your database's dialect accordingly{% endif %}. {% if async %}Make sure to set `generateAsync` to 
 `true` when creating your database.{% endif %} 
 
 === "Kotlin"

docs/common/index_queries.md

@@ -1,6 +1,8 @@
-SQL statements inside a `.sq` file can be labeled to have a typesafe function generated for them available at runtime.
+## Defining Typesafe Queries
 
-```sql
+SQLDelight will generate a typesafe function for any labeled SQL statement in a `.sq` file.
+
+```sql title="src/main/sqldelight/com/example/sqldelight/hockey/data/Player.sq"
 selectAll:
 SELECT *
 FROM hockeyPlayer;
@@ -14,25 +16,32 @@ INSERT INTO hockeyPlayer(player_number, full_name)
 VALUES ?;
 ```
 
-Files with labeled statements in them will have a queries file generated from them that matches the `.sq` file name - putting the above sql into `Player.sq` generates `PlayerQueries.kt`. To get a reference to `PlayerQueries` you need to wrap the driver we made above:
+A "Queries" object will be generated for each `.sq` file containing labeled statements.
+For example, a `PlayerQueries` object will be generated for the `Player.sq` file shown above.
+This object can be used to call the generated typesafe functions which will execute the actual SQL
+statements.
 
 ```kotlin
-// In reality the database and driver above should be created a single time
-// and passed around using your favourite dependency injection/service
-// locator/singleton pattern.
-val database = Database(driver)
-
-val playerQueries: PlayerQueries = database.playerQueries
+{% if async %}suspend {% endif %}fun doDatabaseThings(driver: SqlDriver) {
+  val database = Database(driver)
+  val playerQueries: PlayerQueries = database.playerQueries
 
-println(playerQueries.selectAll().executeAsList())
-// Prints [HockeyPlayer(15, "Ryan Getzlaf")]
+  println(playerQueries.selectAll().{% if async %}await{% else %}execute{% endif %}AsList()) 
+  // [HockeyPlayer(15, "Ryan Getzlaf")]
 
-playerQueries.insert(player_number = 10, full_name = "Corey Perry")
-println(playerQueries.selectAll().executeAsList())
-// Prints [HockeyPlayer(15, "Ryan Getzlaf"), HockeyPlayer(10, "Corey Perry")]
+  playerQueries.insert(player_number = 10, full_name = "Corey Perry")
+  println(playerQueries.selectAll().{% if async %}await{% else %}execute{% endif %}AsList()) 
+  // [HockeyPlayer(15, "Ryan Getzlaf"), HockeyPlayer(10, "Corey Perry")]
 
-val player = HockeyPlayer(10, "Ronald McDonald")
-playerQueries.insertFullPlayerObject(player)
+  val player = HockeyPlayer(10, "Ronald McDonald")
+  playerQueries.insertFullPlayerObject(player)
+}
 ```
 
-And that's it! Check out the other pages on the sidebar for other functionality.
+{% if async %}
+!!! warning
+    When using an asynchronous driver, use the suspending `awaitAs*()` extension functions when 
+    running queries instead of the blocking `executeAs*()` functions.
+{% endif %}
+
+And that's it! Check out the other pages on the sidebar for other functionality.

docs/common/index_schema.md

@@ -1,5 +1,6 @@
 {% include 'common/index_schema_sq.md' %}
 
-From this, SQLDelight will generate a `Database` Kotlin class with an associated `Schema` object that can be used to create your database and run your statements on it. Generating the `Database` file happens during the 'generateSqlDelightInterface' gradle task. This task runs during the 'make project'/'make module' build task, or automatically if you have the SQLDelight IDE plugin.
-
-Accessing the generated database also requires a driver, which SQLDelight provides implementations of:
+From these statements, SQLDelight will generate a `Database` class with an associated `Schema`
+object that can be used to create your database and execute statements on it. The `Database` class
+is generated by the `generateSqlDelightInterface` Gradle task which is run automatically by the
+SQLDelight IDE plugin when you edit a `.sq` file, and also as part of a normal Gradle build.

docs/common/index_schema_sq.md

@@ -1,8 +1,10 @@
-Put your SQL statements in a `.sq` file under `src/main/sqldelight`. Typically the first statement in the SQL file creates a table.
+{% if not server %}## Defining the Schema{% endif %}
 
-```sql
--- src/main/sqldelight/com/example/sqldelight/hockey/data/Player.sq
+Write your SQL statements in a `.sq` file under `src/main/sqldelight`. 
+Typically the first statement in the `.sq` file creates a table, but you can also create indexes
+or set up default content.
 
+```sql title="src/main/sqldelight/com/example/sqldelight/hockey/data/Player.sq"
 CREATE TABLE hockeyPlayer (
   player_number INTEGER PRIMARY KEY NOT NULL,
   full_name TEXT NOT NULL

docs/js_sqlite/index.md

@@ -3,7 +3,7 @@ async: true
 ---
 # Getting started with SQLDelight on Kotlin/JS
 
-!!! warning
+!!! info
     The synchronous `sqljs-driver` (pre-2.0) has been replaced with the asynchronous `web-worker-driver`.
     This requires configuring the `generateAsync` setting in your Gradle configuration.
 

docs/js_sqlite/sqljs_worker.md

@@ -1,6 +1,6 @@
 # SQL.js Web Worker
 
-!!! example
+!!! example "Experimental"
     The SQL.js worker is not yet being published to NPM. It can be built locally by running the
     `./gradlew :drivers:web-worker-driver:sqljs:assembleJsPackage`, and the assembled package can
     be then used as a local file dependency.

docs/jvm_h2/index.md

@@ -1,13 +1,12 @@
 ---
 dialect: "app.cash.sqldelight:hsql-dialect"
+server: true
 ---
-# 👷‍♀️ IN DEVELOPMENT 
+# :material-test-tube: Getting Started with HSQL on JVM
 
-H2 is still incubating, and pieces of the dialect are missing. If you are using it
-and encounter parts of the dialect which are unsupported, please report at
-[sql-psi](https://github.com/AlecStrong/sql-psi)
-
-## Getting Started with H2
+!!! example "Experimental"
+    HSQL support is incubating, and pieces of the dialect are still missing. If you encounter parts 
+    of the dialect which are unsupported, please report it at [sql-psi](https://github.com/AlecStrong/sql-psi).
 
 {% include 'common/index_gradle_database.md' %}
 

docs/jvm_mysql/index.md

@@ -1,7 +1,8 @@
 ---
 dialect: "app.cash.sqldelight:mysql-dialect"
+server: true
 ---
-# Getting Started with MySQL
+# Getting Started with MySQL on JVM
 
 {% include 'common/index_gradle_database.md' %}
 

docs/jvm_postgresql/index.md

@@ -1,7 +1,8 @@
 ---
 dialect: "app.cash.sqldelight:postgresql-dialect"
+server: true
 ---
-# Getting Started with PostgreSQL
+# Getting Started with PostgreSQL on JVM
 
 {% include 'common/index_gradle_database.md' %}
 

docs/jvm_sqlite/index.md

@@ -4,6 +4,9 @@
 
 {% include 'common/index_schema.md' %}
 
+To use the generated database in your code, you must add the SQLDelight SQLite driver dependency to
+your project.
+
 === "Kotlin"
     ```groovy
     dependencies {
@@ -16,9 +19,20 @@
       implementation "app.cash.sqldelight:sqlite-driver:{{ versions.sqldelight }}"
     }
     ```
-```kotlin
-val driver: SqlDriver = JdbcSqliteDriver(JdbcSqliteDriver.IN_MEMORY)
-Database.Schema.create(driver)
-```
+
+An instance of the driver can be constructed as shown below. The constructor accepts a JDBC 
+connection string that specifies the location of the database file. The `IN_MEMORY`
+constant can also be passed to the constructor to create an in-memory database.
+
+=== "On-Disk"
+    ```kotlin
+    val driver: SqlDriver = JdbcSqliteDriver("jdbc:sqlite:test.db")
+    Database.Schema.create(driver)
+    ```
+=== "In-Memory"
+    ```kotlin
+    val driver: SqlDriver = JdbcSqliteDriver(JdbcSqliteDriver.IN_MEMORY)
+    Database.Schema.create(driver)
+    ```
 
 {% include 'common/index_queries.md' %}

docs/multiplatform_sqlite/index.md

@@ -1,37 +1,20 @@
-# Getting Started with Multiplatform
+# Getting Started with SQLite on Multiplatform
 
 {% include 'common/index_gradle_database.md' %}
 
-Put your SQL statements in a `.sq` file under `src/commonMain/sqldelight`. Typically the first statement in the SQL file creates a table.
+{% include 'common/index_schema.md' %}
 
-```sql
--- src/commonMain/sqldelight/com/example/sqldelight/hockey/data/Player.sq
-
-CREATE TABLE hockeyPlayer (
-  player_number INTEGER NOT NULL,
-  full_name TEXT NOT NULL
-);
-
-CREATE INDEX hockeyPlayer_full_name ON hockeyPlayer(full_name);
-
-INSERT INTO hockeyPlayer (player_number, full_name)
-VALUES (15, 'Ryan Getzlaf');
-```
-
-From this, SQLDelight will generate a `Database` Kotlin class with an associated `Schema` object that can be used to create your database and run your statements on it. Generating the `Database` file happens during the 'generateSqlDelightInterface' gradle task. This task runs during the 'make project'/'make module' build task, or automatically if you have the SQLDelight IDE plugin.
-
-Accessing the generated database also requires a driver, which SQLDelight provides implementations of:
+To use the generated database in your code, you must add a SQLDelight driver dependency to your project.
+Each target platform has its own driver implementation.
 
 === "Kotlin"
     ```kotlin
-    kotlin {
-      // The drivers needed will change depending on what platforms you target:
-
+    kotlin { 
       sourceSets.androidMain.dependencies {
         implementation("app.cash.sqldelight:android-driver:{{ versions.sqldelight }}")
       }
 
-      // or sourceSets.iosMain, sourceSets.windowsMain, etc.
+      // or iosMain, windowsMain, etc.
       sourceSets.nativeMain.dependencies {
         implementation("app.cash.sqldelight:native-driver:{{ versions.sqldelight }}")
       }
@@ -43,14 +26,12 @@ Accessing the generated database also requires a driver, which SQLDelight provid
     ```
 === "Groovy"
     ```groovy
-    kotlin {
-      // The drivers needed will change depending on what platforms you target:
-
+    kotlin { 
       sourceSets.androidMain.dependencies {
         implementation "app.cash.sqldelight:android-driver:{{ versions.sqldelight }}"
       }
 
-      // or sourceSets.iosMain, sourceSets.windowsMain, etc.
+      // or iosMain, windowsMain, etc.
       sourceSets.nativeMain.dependencies {
         implementation "app.cash.sqldelight:native-driver:{{ versions.sqldelight }}"
       }
@@ -61,9 +42,9 @@ Accessing the generated database also requires a driver, which SQLDelight provid
     }
     ```
 
-## Creating Drivers
+## Constructing Driver Instances
 
-Create a factory class or method to obtain a `SqlDriver` instance in your common code. 
+Create a common factory class or method to obtain a `SqlDriver` instance. 
 
 ```kotlin title="src/commonMain/kotlin"
 import com.example.Database
@@ -111,6 +92,4 @@ Then implement this for each target platform:
 
 For use with Kotlin/JS, [see here](../js_sqlite/multiplatform).
 
-## Using Queries
-
 {% include 'common/index_queries.md' %}

docs/native_sqlite/index.md

@@ -1,13 +1,19 @@
 # Getting started with SQLDelight on Kotlin/Native
 
+!!! info "Kotlin/Native Memory Manager"
+    Since SQLDelight 2.0, the SQLDelight Native driver only supports Kotlin/Native's [new memory manager].
+
 {% include 'common/index_gradle_database.md' %}
 
 {% include 'common/index_schema.md' %}
 
+To use the generated database in your code, you must add the SQLDelight Native driver dependency to
+your project.
+
 === "Kotlin"
     ```kotlin
     kotlin {
-      // or sourceSets.iosMain, sourceSets.windowsMain, etc.
+      // or iosMain, windowsMain, etc.
       sourceSets.nativeMain.dependencies {
         implementation("app.cash.sqldelight:native-driver:{{ versions.sqldelight }}")
       }
@@ -16,26 +22,25 @@
 === "Groovy"
     ```groovy
     kotlin {
-      // or sourceSets.iosMain, sourceSets.windowsMain, etc.
+      // or iosMain, windowsMain, etc.
       sourceSets.nativeMain.dependencies {
         implementation "app.cash.sqldelight:native-driver:{{ versions.sqldelight }}"
       }
     }
     ```
 
+An instance of the driver can be constructed as shown below, and requires a reference to the generated `Schema` object.
+
 ```kotlin
 val driver: SqlDriver = NativeSqliteDriver(Database.Schema, "test.db")
 ```
 
-### Kotlin/Native Memory Models
-
-The SQLDelight native driver supports the updated memory model only since 2.0.0.
-
 {% include 'common/index_queries.md' %}
 
 ## Reader Connection Pools
 
-Disk databases can (optionally) have multiple reader connections. To configure the reader pool, pass the `maxReaderConnections` parameter to the various constructors of `NativeSqliteDriver`:
+Disk databases can (optionally) have multiple reader connections. To configure the reader pool, pass 
+the `maxReaderConnections` parameter to the various constructors of `NativeSqliteDriver`:
 
 ```kotlin
 val driver: SqlDriver = NativeSqliteDriver(
@@ -45,5 +50,7 @@ val driver: SqlDriver = NativeSqliteDriver(
 )
 ```
 
-Reader connections are only used to run queries outside of a transaction. Any write calls, and anything in a transaction, 
-uses a single connection dedicated to transactions.
+Reader connections are only used to run queries outside of a transaction. Any write calls, and 
+anything in a transaction, uses a single connection dedicated to transactions.
+
+[new memory manager]: https://kotlinlang.org/docs/native-memory-manager.html