flesh out docs site (#108)

Author: sargunv

build.gradle.kts

@@ -2,10 +2,8 @@
 
 import com.vanniktech.maven.publish.SonatypeHost
 import fr.brouillard.oss.jgitver.Strategies
-import kotlin.time.Duration.Companion.seconds
-import kotlin.time.toJavaDuration
 import org.jetbrains.kotlin.gradle.ExperimentalWasmDsl
-import org.jetbrains.kotlin.gradle.targets.js.dsl.KotlinJsSubTargetDsl
+import ru.vyarus.gradle.plugin.mkdocs.task.MkdocsTask
 
 plugins {
   alias(libs.plugins.kotlin.multiplatform)
@@ -34,27 +32,14 @@ kotlin {
 
   jvm()
 
-  fun KotlinJsSubTargetDsl.configureWithKarma() {
-    testTask {
-      useKarma {
-        useChromeHeadless()
-        timeout = 60.seconds.toJavaDuration()
-      }
-    }
-  }
-
-  fun KotlinJsSubTargetDsl.configureWithMocha() {
-    testTask { useMocha { timeout = "60s" } }
-  }
-
   js(IR) {
-    browser { configureWithMocha() }
-    nodejs { configureWithMocha() }
+    browser()
+    nodejs()
   }
 
   wasmJs {
-    browser { configureWithMocha() }
-    nodejs { configureWithMocha() }
+    browser()
+    nodejs()
     d8 {}
   }
 
@@ -77,6 +62,7 @@ kotlin {
   tvosArm64()
 
   // native tier 3
+  // android native platforms aren't supported due to lack of Ktor support
   mingwX64()
   watchosDeviceArm64()
 
@@ -159,9 +145,10 @@ dokka {
         remoteUrl("https://github.com/PokeAPI/pokekotlin/tree/${project.ext["base_tag"]}/")
         localDirectory.set(rootDir)
       }
-      externalDocumentationLinks {
-        // TODO
-      }
+      externalDocumentationLinks { create("ktor") { url("https://api.ktor.io/") } }
+      suppressedFiles.from(
+        "build/generated/ksp/metadata/commonMain/kotlin/dev/sargunv/pokekotlin/_PokeApiImpl.kt"
+      )
     }
   }
 }
@@ -174,6 +161,12 @@ mkdocs {
   }
 }
 
+tasks.withType<MkdocsTask>().configureEach {
+  val releaseVersion = ext["base_tag"].toString().replace("v", "")
+  val snapshotVersion = "${ext["next_patch_version"]}-SNAPSHOT"
+  extras.set(mapOf("release_version" to releaseVersion, "snapshot_version" to snapshotVersion))
+}
+
 tasks.register("generateDocs") {
   dependsOn("dokkaGenerate", "mkdocsBuild")
   doLast {

docs/docs/index.md

@@ -1,7 +1,98 @@
 # Overview
 
-PokeKotlin is a [Kotlin](https://kotlinlang.org/) client for
-[PokeApi](https://github.com/PokeAPI/pokeapi).
+## Introduction
 
-Documentation is under construction. For now, see the
-[API Reference](./api/index.html).
+PokeKotlin is a modern [Kotlin Multiplatform] client for [PokéAPI]. You can use
+it to integrate all sorts of Pokémon data into your Kotlin projects.
+
+Under the hood, it's built on [Ktor], [Kotlin Serialization], and coroutines.
+
+## Supported platforms
+
+- Kotlin/JVM, including Android
+- Kotlin/JS for browser and Node
+- Kotlin/WASM for browser and Node
+- Kotlin/Native for Linux, Windows, macOS, iOS, tvOS, and watchOS
+
+## Installation
+
+This library is published via [Maven Central], and snapshot builds of `main` are
+additionally available on [GitHub Packages].
+
+=== "Releases (Maven Central)"
+
+    The latest release is **v{{ gradle.release_version }}**. In your Gradle version catalog, add:
+
+    ```toml title="libs.versions.toml"
+    [libraries]
+    pokekotlin = { module = "dev.sargunv.pokekotlin:pokekotlin", version = "{{ gradle.release_version }}" }
+    ```
+
+=== "Snapshots (GitHub Packages)"
+
+    !!! warning
+
+        The published documentation is for the latest release, and may not match the snapshot
+        version. If using snapshots, always refer to the [latest source code][repo] for the most
+        accurate information.
+
+    First, follow [GitHub's guide][gh-packages-guide] for authenticating to GitHub Packages. Your
+    settings.gradle.kts should have something like this:
+
+    ```kotlin title="settings.gradle.kts"
+    repositories {
+      maven {
+        url = uri("https://maven.pkg.github.com/pokeapi/pokekotlin")
+        credentials {
+          username = project.findProperty("gpr.user") as String? ?: System.getenv("GH_USERNAME")
+          password = project.findProperty("gpr.key") as String? ?: System.getenv("GH_TOKEN")
+        }
+      }
+    }
+    ```
+
+    The latest snapshot is **v{{ gradle.snapshot_version }}**. In your Gradle version catalog, add:
+
+    ```toml title="libs.versions.toml"
+    [libraries]
+    pokekotlin = { module = "dev.sargunv.pokekotlin:pokekotlin", version = "{{ gradle.snapshot_version }}" }
+    ```
+
+In your Gradle build script, add:
+
+```kotlin title="build.gradle.kts"
+commonMain.dependencies {
+  implementation(libs.maplibre.compose)
+}
+```
+
+## Usage
+
+For basic usage, use the global `PokeApi` instance:
+
+```kotlin
+-8<- "src/commonTest/kotlin/dev/sargunv/pokekotlin/example/example.kt:simple"
+```
+
+By default, the client will connect to the official `https://pokeapi.co/`
+instance and cache results in memory.
+
+If you want to customize the client, create a custom instance of the client:
+
+```kotlin
+-8<- "src/commonTest/kotlin/dev/sargunv/pokekotlin/example/example.kt:custom"
+```
+
+For further details, see the Dokka [API Reference](./api).
+
+[Kotlin Multiplatform]: https://kotlinlang.org/docs/multiplatform.html
+[PokéAPI]: https://pokeapi.co/
+[Maven Central]: https://central.sonatype.com/namespace/dev.sargunv.pokekotlin
+[GitHub Packages]:
+  https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-gradle-registry
+[gh-packages-guide]:
+  https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-gradle-registry#using-a-published-package
+[repo]: https://github.com/pokeapi/pokekotlin
+[Ktor]: https://ktor.io/
+[Kotlin Serialization]: https://github.com/Kotlin/kotlinx.serialization
+[coroutines]: https://kotlinlang.org/docs/coroutines-guide.html

src/commonMain/kotlin/dev/sargunv/pokekotlin/PokeApi.kt

@@ -1,5 +1,3 @@
-@file:JvmName("PokeApiClient")
-
 package dev.sargunv.pokekotlin
 
 import de.jensklingenberg.ktorfit.Ktorfit.Builder
@@ -68,7 +66,6 @@ import io.ktor.client.plugins.cache.storage.CacheStorage
 import io.ktor.client.plugins.contentnegotiation.ContentNegotiation
 import io.ktor.http.ContentType
 import io.ktor.serialization.kotlinx.json.json
-import kotlin.jvm.JvmName
 
 interface PokeApi {
 
@@ -563,7 +560,6 @@ interface PokeApi {
   companion object : PokeApi by PokeApi()
 }
 
-@JvmName("create")
 fun PokeApi(
   baseUrl: String = "https://pokeapi.co/api/v2/",
   engine: HttpClientEngine = getDefaultEngine(),

src/commonTest/kotlin/dev/sargunv/pokekotlin/example/example.kt

@@ -0,0 +1,18 @@
+package dev.sargunv.pokekotlin.example
+
+import dev.sargunv.pokekotlin.PokeApi
+
+suspend fun simple() {
+  // -8<- [start:simple]
+  val bulbasaur = PokeApi.getPokemon(1)
+  println(bulbasaur)
+  // -8<- [end:simple]
+}
+
+suspend fun custom() {
+  // -8<- [start:custom]
+  val client = PokeApi(baseUrl = "https://localhost:8080")
+  val bulbasaur = client.getPokemon(1)
+  println(bulbasaur)
+  // -8<- [end:custom]
+}