Add Smithy Kotlin documentation

.changes/next-release/documentation-101a6c8f40db121d355c5c9c7b5143b7a7a41a7c.json

@@ -0,0 +1,7 @@
+{
+  "type": "documentation",
+  "description": "Added Smithy Kotlin Quickstart and Client User Guide sections.",
+  "pull_requests": [
+    "[#2944](https://github.com/smithy-lang/smithy/pull/2944)"
+  ]
+}

docs/source-2.0/languages/kotlin/client/generating-clients.rst

@@ -0,0 +1,184 @@
+==================
+Generating Clients
+==================
+
+The Smithy Kotlin :ref:`build plugin <plugins>`, ``kotlin-codegen``, generates Kotlin clients from Smithy models,
+and can be executed with `Gradle <https://gradle.org/>`_ (recommended) or the :ref:`Smithy CLI <smithy-cli>`.
+
+.. admonition:: Important
+    :class: note
+
+    The Smithy CLI is a prerequisite for this guide.
+    See the :doc:`Smithy CLI installation guide </guides/smithy-cli/cli_installation>`
+    if you do not already have the CLI installed.
+
+-----------------------------------
+Initial setup: Gradle (recommended)
+-----------------------------------
+
+To generate a Kotlin client for a service, start by creating a new Smithy Gradle project.
+
+The ``smithy init`` CLI command can be used to create a new Smithy Gradle project:
+
+.. code-block:: sh
+
+    smithy init -t quickstart-gradle
+
+A Smithy Gradle project should contain a Gradle settings file, a Gradle build script,
+a :ref:`smithy-build.json <smithy-build>` configuration file, and a `model/` directory
+containing Smithy models. For example:
+
+.. code-block:: sh
+
+    my-project/
+    ├── model/
+    │   ├── ...
+    ├── smithy-build.json
+    ├── build.gradle.kts
+    └── settings.gradle.kts
+
+To your Gradle build script, apply the the `Kotlin JVM <https://plugins.gradle.org/plugin/org.jetbrains.kotlin.jvm>`_ plugin,
+and the `smithy-base <https://github.com/smithy-lang/smithy-gradle-plugin#smithy-base-plugin>`_ plugin (for building your Smithy model):
+
+.. code-block:: diff
+   :caption: build.gradle.kts
+
+   plugins {
+   +    kotlin("jvm") version "2.3.0"
+   +    id("software.amazon.smithy.gradle.smithy-base") version "1.3.0"
+   }
+
+Add a `version catalog <https://docs.gradle.org/current/userguide/version_catalogs.html>`_ to manage your dependencies and their versions:
+
+.. code-block:: toml
+    :caption: gradle/libs.versions.toml
+
+    smithy-kotlin-version="1.6.0"
+    coroutines-core-version="1.10.2"
+
+    smithy-kotlin-codegen = { module = "aws.smithy.kotlin:codegen", version.ref = "smithy-kotlin-version" }
+
+    smithy-kotlin-runtime-core = { module = "aws.smithy.kotlin:runtime-core", version.ref = "smithy-kotlin-version" }
+    smithy-kotlin-smithy-client = { module = "aws.smithy.kotlin:smithy-client", version.ref = "smithy-kotlin-version" }
+    smithy-kotlin-http-client = { module = "aws.smithy.kotlin:http-client", version.ref = "smithy-kotlin-version" }
+    smithy-kotlin-telemetry-api = { module = "aws.smithy.kotlin:telemetry-api", version.ref = "smithy-kotlin-version" }
+    smithy-kotlin-telemetry-defaults = { module = "aws.smithy.kotlin:telemetry-defaults", version.ref = "smithy-kotlin-version" }
+    smithy-kotlin-rpcv2-protocol = { module = "aws.smithy.kotlin:smithy-rpcv2-protocols", version.ref = "smithy-kotlin-version" }
+    smithy-kotlin-aws-protocol-core = { module = "aws.smithy.kotlin:aws-protocol-core", version.ref = "smithy-kotlin-version" }
+    smithy-kotlin-aws-signing-common = { module = "aws.smithy.kotlin:aws-signing-common", version.ref = "smithy-kotlin-version" }
+    smithy-kotlin-serde = { module = "aws.smithy.kotlin:serde", version.ref = "smithy-kotlin-version" }
+    smithy-kotlin-serde-cbor = { module = "aws.smithy.kotlin:serde-cbor", version.ref = "smithy-kotlin-version" }
+    smithy-kotlin-http-client-engine-default = { module = "aws.smithy.kotlin:http-client-engine-default", version.ref = "smithy-kotlin-version" }
+
+    kotlinx-coroutines-core = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "coroutines-core-version" }
+
+Add the following dependencies to your project:
+
+.. code-block:: kotlin
+   :caption: build.gradle.kts
+
+    dependencies {
+        // Code generator
+        compileOnly(libs.smithy.kotlin.codegen)
+
+        // Client Dependencies
+        implementation(libs.smithy.kotlin.runtime.core)
+        implementation(libs.smithy.kotlin.smithy.client)
+        implementation(libs.smithy.kotlin.http.client)
+        implementation(libs.smithy.kotlin.telemetry.api)
+        implementation(libs.smithy.kotlin.telemetry.defaults)
+        implementation(libs.smithy.kotlin.rpcv2.protocol)
+        implementation(libs.smithy.kotlin.aws.protocol.core)
+        implementation(libs.smithy.kotlin.aws.signing.common)
+        implementation(libs.smithy.kotlin.serde)
+        implementation(libs.smithy.kotlin.serde.cbor)
+        implementation(libs.smithy.kotlin.http.client.engine.default)
+        implementation(libs.kotlinx.coroutines.core)
+    }
+
+Now, define a service model in a ``model/`` directory at the root of your project.
+The ``smithy-base`` Gradle plugin will automatically discover any models added to that directory.
+
+---------------------------
+Configuring code generation
+---------------------------
+
+In order to execute code generation, the ``kotlin-codegen`` plugin must be added to
+your :ref:`smithy-build <smithy-build>` config:
+
+.. code-block:: diff
+   :caption: smithy-build.json
+
+   {
+     "version": "1.0",
+     "plugins": {
+   +     "kotlin-codegen": {
+   +       "service": "com.example#CoffeeShop", // Replace with your service's ID
+   +       "sdkId": "CoffeeShop", // Replace with your service's SDK ID
+   +       "package": {
+   +         "name": "io.smithy.kotlin.client.example", // Generated Kotlin code will use this as the root package namespace
+   +         "version": "0.0.1"
+   +       }
+   +     }
+     }
+   }
+
+------------------------------------
+Add Smithy build to the Kotlin build
+------------------------------------
+
+To ensure your client code is generated on every Kotlin build, Gradle must be configured to run a Smithy build before
+Kotlin compilation in your Gradle build script:
+
+.. code-block:: kotlin
+    :caption: build.gradle.kts
+
+    tasks.named("compileKotlin") {
+        dependsOn("smithyBuild")
+    }
+
+------------------------------------------
+Add generated code to the Kotlin sourceSet
+------------------------------------------
+
+Your package is now configured to generate Kotlin client source code. However, the generated code must be added to a
+`source set <https://docs.gradle.org/current/dsl/org.gradle.api.tasks.SourceSet.html>`_ to be compiled.
+To add the generated code to the main source set, add the following to your Gradle build script:
+
+.. code-block:: kotlin
+    :caption: build.gradle.kts
+
+    afterEvaluate {
+        val clientPath = smithy.getPluginProjectionPath(smithy.sourceProjection.get(), "kotlin-codegen")
+        sourceSets.main.get().kotlin.srcDir(clientPath)
+    }
+
+
+-----------------------
+Opt in to internal APIs
+-----------------------
+
+Some of the code generated client APIs are public but marked with an `InternalApi <https://github.com/smithy-lang/smithy-kotlin/blob/main/runtime/runtime-core/common/src/aws/smithy/kotlin/runtime/Annotations.kt#L8-L31>`_
+annotation to discourage client end users from using them outside of generated code.
+To opt in to the InternalApi annotation, add the following to your Gradle build script:
+
+.. code-block:: kotlin
+    :caption: build.gradle.kts
+
+    val optinAnnotations = listOf("kotlin.RequiresOptIn", "aws.smithy.kotlin.runtime.InternalApi")
+    kotlin.sourceSets.all {
+        optinAnnotations.forEach { languageSettings.optIn(it) }
+    }
+
+---------------
+Generating code
+---------------
+
+To generate and compile your client code, run a build from the root of your Gradle project:
+
+.. code-block:: sh
+
+    ./gradlew clean build
+
+Building the project will generate code in the
+``build/smithy-projections/<project-name>/source/kotlin-codegen/`` directory.

docs/source-2.0/languages/kotlin/client/index.rst

@@ -0,0 +1,15 @@
+=================
+Client User Guide
+=================
+
+This guide walks through how to use `Smithy Kotlin <https://github.com/smithy-lang/smithy-kotlin>`_ to generate
+Kotlin clients from a Smithy model of a service.
+
+For a general overview of the Smithy IDL, see the Smithy :doc:`/quickstart` Guide
+
+For a general introduction to the Smithy Kotlin framework, see the Smithy :doc:`../quickstart` Guide.
+
+.. toctree::
+    :maxdepth: 1
+
+    generating-clients

docs/source-2.0/languages/kotlin/index.rst

@@ -2,12 +2,16 @@
 Kotlin
 ======
 
-.. warning::
+.. toctree::
+    :maxdepth: 1
 
-       Smithy Kotlin is currently in development and documentation is under construction
+    quickstart
+    client/index
 
 .. toctree::
     :caption: References
     :maxdepth: 1
 
     Source code <https://github.com/smithy-lang/smithy-kotlin>
+    Smithy Kotlin Examples <https://github.com/smithy-lang/smithy-examples/tree/main/smithy-kotlin-examples>
+    Smithy Kotlin Design Docs <https://github.com/smithy-lang/smithy-kotlin/tree/main/docs/design>