docs: bootstrap API reference docs generation (#119)

Author: aajtodd

CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## [Unreleased]
 
+## [0.2.0-M1] - 05/07/2021
+
+**WARNING: Beta releases may contain bugs and no guarantee is made about API stability. They are not recommended for production use!**
+
+### Services new in this release
+
+* S3
+    * NOTE: S3 is a complicated service, this initial release **DOES NOT** have complete support for all S3 features.
+
+## Changes
+
+* (feat): add conversions to/from `java.time.Instant` and SDK `Instant` (https://github.com/awslabs/smithy-kotlin/issues/271)
+* (fix): generate per/service base exception types (https://github.com/awslabs/smithy-kotlin/issues/233)
+
+
 ## [0.1.0-M0] - 03/19/2021
 
 **WARNING: Beta releases may contain bugs and no guarantee is made about API stability. They are not recommended for production use!**

README.md

@@ -17,7 +17,7 @@ See the [Getting Started Guide](docs/GettingStarted.md)
 Generated sources are not checked into the repository, you first have to generate the clients before you can build them.
 
 
-```
+```sh
 ./gradlew :codegen:sdk:bootstrap
 ```
 
@@ -28,7 +28,7 @@ NOTE: To re-run codegen for the same set of services multiple times add the `--r
 After generating the services you care about they are available to build:
 
 e.g.
-```
+```sh
 ./gradlew :services:lambda:build
 ```
 
@@ -37,6 +37,33 @@ Where the task follows the pattern: `:services:SERVICE:build`
 
 To see list of all projects run `./gradlew projects`
 
+##### Generating a single service
+See the local.properties definition above to specify this in a config file.
+
+```sh
+./gradlew -Paws.services=lambda  :codegen:sdk:bootstrap
+```
+
+##### Testing Locally
+Testing generated services generally requires publishing artifacts (e.g. client-runtime) of `smithy-kotlin`, `aws-crt-kotlin`, and `aws-sdk-kotin` to maven local.
+
+#### Generating API Documentation
+
+API documentation is generated using [Dokka](http://kotlin.github.io/dokka) which is the official documentation tool maintained by JetBrains for documenting Kotlin code.
+
+Unlike Java, Kotlin uses it's own [KDoc](https://kotlinlang.org/docs/kotlin-doc.html) format.
+
+
+To generate API reference documentation for the AWS Kotlin SDK:
+
+
+```sh
+./gradlew --no-daemon --no-parallel dokkaHtmlMultiModule
+```
+
+This will output HTML formatted documentation to `build/dokka/htmlMultiModule`
+
+NOTE: You currently need an HTTP server to view the documentation in browser locally. You can either use the builtin server in Intellij or use your favorite local server (e.g. `python3 -m http.server`). See [Kotlin/dokka#1795](https://github.com/Kotlin/dokka/issues/1795)
 
 ### Build properties
 
@@ -55,12 +82,3 @@ aws.services=lambda
 ```
 
 
-##### Generating a single service
-See the local.properties definition above to specify this in a config file.
-
-```
-./gradlew -Paws.services=lambda  :codegen:sdk:bootstrap
-```
-
-##### Testing Locally
-Testing generated services generally requires publishing artifacts (e.g. client-runtime) of `smithy-kotlin`, `aws-crt-kotlin`, and `aws-sdk-kotin` to maven local.

build.gradle.kts

@@ -4,15 +4,73 @@
  */
 plugins {
     kotlin("jvm") version "1.4.31" apply false
+    id("org.jetbrains.dokka")
+}
+
+dependencies {
+    dokkaPlugin(project(":dokka-aws"))
 }
 
 allprojects {
     repositories {
         mavenLocal()
         mavenCentral()
+        // for dokka
+        maven("https://maven.pkg.jetbrains.space/public/p/kotlinx-html/maven") {
+            content {
+                includeGroup("org.jetbrains.kotlinx")
+            }
+        }
+    }
+
+    tasks.withType<org.jetbrains.dokka.gradle.DokkaTaskPartial>().configureEach {
+        // each module can include their own top-level module documentation
+        // see https://kotlinlang.org/docs/kotlin-doc.html#module-and-package-documentation
+        if (project.file("API.md").exists()) {
+            dokkaSourceSets.configureEach {
+                includes.from(project.file("API.md"))
+            }
+        }
+    }
+
+    tasks.withType<org.jetbrains.dokka.gradle.AbstractDokkaTask>().configureEach {
+        val sdkVersion: String by project
+        moduleVersion.set(sdkVersion)
+
+        val year = java.time.LocalDate.now().year
+        val pluginConfigMap = mapOf(
+            "org.jetbrains.dokka.base.DokkaBase" to """
+                {
+                    "customStyleSheets": ["${rootProject.file("docs/api/css/logo-styles.css")}"],
+                    "customAssets": [
+                        "${rootProject.file("docs/api/assets/logo-icon.svg")}",
+                        "${rootProject.file("docs/api/assets/aws_logo_white_59x35.png")}"
+                    ],
+                    "footerMessage": "© $year, Amazon Web Services, Inc. or its affiliates. All rights reserved."
+                }
+            """
+        )
+        pluginsMapConfiguration.set(pluginConfigMap)
     }
 }
 
+// configure the root multimodule docs
+tasks.dokkaHtmlMultiModule {
+    moduleName.set("AWS Kotlin SDK")
+
+    includes.from(
+        // NOTE: these get concatenated
+        rootProject.file("docs/api/README.md"),
+        rootProject.file("docs/GettingStarted.md")
+    )
+
+    val excludeFromDocumentation = listOf(
+        project(":client-runtime:testing"),
+        project(":client-runtime:crt-util")
+    )
+    removeChildTasks(excludeFromDocumentation)
+}
+
 val ktlint: Configuration by configurations.creating
 val ktlintVersion: String by project
 dependencies {
@@ -22,7 +80,8 @@ dependencies {
 val lintPaths = listOf(
     "codegen/smithy-aws-kotlin-codegen/**/*.kt",
     "client-runtime/**/*.kt",
-    "examples/**/*.kt"
+    "examples/**/*.kt",
+    "dokka-aws/**/*.kt"
 )
 
 tasks.register<JavaExec>("ktlint") {

client-runtime/aws-client-rt/common/src/aws/sdk/kotlin/runtime/Annotations.kt

@@ -12,7 +12,7 @@ package aws.sdk.kotlin.runtime
  * any strange effects.
  *
  * We strongly recommend to not use such API.
- *
+ * @suppress
  */
 @Suppress("DEPRECATION")
 @RequiresOptIn(

client-runtime/build.gradle.kts

@@ -7,7 +7,7 @@ description = "AWS client runtime support for generated service clients"
 
 plugins {
     kotlin("multiplatform")
-    id("org.jetbrains.dokka") version "1.4.20"
+    id("org.jetbrains.dokka")
     jacoco
 }
 
@@ -82,6 +82,10 @@ subprojects {
     }
 
     apply(from = rootProject.file("gradle/publish.gradle"))
+
+    dependencies {
+        dokkaPlugin(project(":dokka-aws"))
+    }
 }
 
 // FIXME - resolves build deadlock with aws-client-rt when using composite builds

docs/GettingStarted.md

@@ -1,14 +1,14 @@
-# Beta Release Quickstart
+## Beta Release Quickstart
 
 Beta releases of the AWS Kotlin SDK are published as a complete maven local repository with all associated dependencies.
 
 
-1. Download the [latest release](https://github.com/awslabs/aws-sdk-kotlin/releases) from Github
+1. Download the [latest release](https://github.com/awslabs/aws-sdk-kotlin/releases) from GitHub
 
 2. Unzip the repository somewhere on your local machine
 
 ```sh
-> unzip aws-sdk-kotlin-0.1.0-M0.zip
+> unzip aws-sdk-kotlin-0.2.0-M1.zip
 ```
 
 There should be a folder named `aws-sdk-kotlin-repo`
@@ -49,11 +49,9 @@ repositories {
 
 4. Add services to your project
 
-Services available for testing: `cognitoidentityprovider`, `dynamodb`, `kms`, `lambda`, `polly`, `secretsmanager`, `translate`
-
 ```kt
 
-val awsKotlinSdkVersion = "0.1.0-M0"
+val awsKotlinSdkVersion = "0.2.0-M1"
 // OR put it in gradle.properties
 // val awsKotlinSdkVersion: String by project
 
@@ -62,8 +60,6 @@ dependencies {
     implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.4.3")
 
     // The following line adds a dependency on the dynamodb client.
-    // Services available in the M0 release:
-    // cognitoidentityprovider, dynamodb, kms, lambda, polly, secretsmanager, translate
     implementation("aws.sdk.kotlin:dynamodb:$awsKotlinSdkVersion")
 
     // The following will cause SDK logs to emit to the console:

docs/api/README.md

@@ -0,0 +1 @@
+# AWS SDK for Kotlin API Reference