docs: bootstrap API reference docs generation (#119)

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

docs/api/css/logo-styles.css

@@ -0,0 +1,25 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0.
+ */
+
+#logo {
+    background-image: url('../images/aws_logo_white_59x35.png');
+    background-color: #232f3e;
+    color: #333;
+    background-size: 59px 35px;
+}
+
+body {
+    background-color: #f2f3f3;
+}
+
+/*
+ * override markdown samples which appear to have broken and/or minimal style
+ */
+.sample-container {
+    padding: 16px;
+    border-radius: 6px;
+    background-color: rgb(280, 280, 280);
+    margin: 12px 0 12px 0;
+}

dokka-aws/build.gradle.kts

@@ -0,0 +1,19 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0.
+ */
+plugins {
+    kotlin("jvm")
+}
+
+description = "Custom Dokka plugin for AWS Kotlin SDK API docs"
+
+dependencies {
+    val dokkaVersion: String by project
+    compileOnly("org.jetbrains.dokka:dokka-base:$dokkaVersion")
+    compileOnly("org.jetbrains.dokka:dokka-core:$dokkaVersion")
+}
+
+tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile> {
+    kotlinOptions.jvmTarget = "1.8"
+}

dokka-aws/src/main/kotlin/aws/sdk/kotlin/dokka/AwsDokkaPlugin.kt

@@ -0,0 +1,25 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0.
+ */
+
+package aws.sdk.kotlin.dokka
+
+import aws.sdk.kotlin.dokka.transformers.FilterInternalApis
+import org.jetbrains.dokka.base.DokkaBase
+import org.jetbrains.dokka.plugability.DokkaPlugin
+
+/**
+ * Dokka plugin for customizing the AWS Kotlin SDK generated API docs
+ */
+class AwsDokkaPlugin : DokkaPlugin() {
+    init {
+        println("AwsDokkaPlugin loaded!")
+    }
+
+    val dokkaBase by lazy { plugin<DokkaBase>() }
+
+    val filterInternalApis by extending {
+        dokkaBase.preMergeDocumentableTransformer providing ::FilterInternalApis
+    }
+}

dokka-aws/src/main/kotlin/aws/sdk/kotlin/dokka/transformers/FilterInternalApis.kt

@@ -0,0 +1,42 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0.
+ */
+
+package aws.sdk.kotlin.dokka.transformers
+
+import org.jetbrains.dokka.base.transformers.documentables.SuppressedByConditionDocumentableFilterTransformer
+import org.jetbrains.dokka.model.*
+import org.jetbrains.dokka.model.properties.WithExtraProperties
+import org.jetbrains.dokka.plugability.DokkaContext
+
+/**
+ * Filters out anything annotated with `InternalSdkApi`
+ */
+class FilterInternalApis(context: DokkaContext) : SuppressedByConditionDocumentableFilterTransformer(context) {
+    override fun shouldBeSuppressed(d: Documentable): Boolean {
+        val isInternal = when (d) {
+            is DClass -> d.isInternalSdk()
+            is DObject -> d.isInternalSdk()
+            is DTypeAlias -> d.isInternalSdk()
+            is DFunction -> d.isInternalSdk()
+            is DProperty -> d.isInternalSdk()
+            is DEnum -> d.isInternalSdk()
+            is DEnumEntry -> d.isInternalSdk()
+            is DTypeParameter -> d.isInternalSdk()
+            else -> false
+        }
+        if (isInternal) println("suppressing ${d.dri}")
+        return isInternal
+    }
+}
+
+fun <T> T.isInternalSdk() where T : WithExtraProperties<out Documentable> =
+    internalAnnotation != null
+
+val <T> T.internalAnnotation where T : WithExtraProperties<out Documentable>
+    get() = extra[Annotations]?.let { annotations ->
+        annotations.directAnnotations.values.flatten().firstOrNull {
+            it.dri.toString() == "aws.sdk.kotlin.runtime/InternalSdkApi///PointingToDeclaration/"
+        }
+    }

dokka-aws/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin

@@ -0,0 +1 @@
+aws.sdk.kotlin.dokka.AwsDokkaPlugin

gradle.properties

@@ -1,5 +1,9 @@
 kotlin.code.style=official
 
+# gradle
+# FIXME - see https://github.com/Kotlin/dokka/issues/1405
+org.gradle.jvmargs=-Xmx4g -XX:MaxMetaspaceSize=1G
+
 # sdk
 sdkVersion=0.2.0-SNAPSHOT
 
@@ -12,6 +16,7 @@ smithyKotlinVersion=0.2.0-SNAPSHOT
 # kotlin
 kotlinVersion=1.4.31
 kotlin.native.ignoreDisabledTargets=true
+dokkaVersion=1.4.32
 
 # kotlin JVM
 kotlinJVMTargetVersion=1.8