docs: bootstrap API reference docs generation

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,32 @@ 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.
+
+```
+./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`
+
 
 ### Build properties
 
@@ -55,12 +81,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/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,3 @@
+# AWS SDK for Kotlin API Reference
+
+Welcome to the API documentation

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