Generate documentation with alpha releases

[aajtodd]

We got some feedback to generate the API documentation independent of the alpha release. This is something we need to look into anyway. This may require some work to integrate dokka, etc. It's also a good excuse to see what our generated API docs look like and figure out how much work we will need to carve out at some point before dev-preview to make them presentable.

[aajtodd]

FWIW I looked into this in-between other things just to see what dokka would output and it took a while to get past some initial issues (there is some kind of memory leak bug - there are already open issues in the dokka repo related to it though):

I was able to get something spit out but it's going to take some work to get it looking right and to get all the modules across repositories represented in a single output:

With the diff below and the following command I could generate documentation independently for either services or the aws-sdk-kotlin client runtime:

./gradlew --no-daemon --no-parallel dokkaHtmlMultiModule

diff --git a/build.gradle.kts b/build.gradle.kts
index 58c9d4e..15794a2 100644
--- a/build.gradle.kts
+++ b/build.gradle.kts
@@ -10,9 +10,24 @@ allprojects {
     repositories {
         mavenLocal()
         mavenCentral()
+        // for dokka
+        maven("https://maven.pkg.jetbrains.space/public/p/kotlinx-html/maven") {
+            content {
+                includeGroup("org.jetbrains.kotlinx")
+            }
+        }
     }
 }
 
+// subprojects {
+//     tasks.withType<DokkaTask>().configureEach {
+//         outputDirectory.set(buildDir.resolve("dokka"))
+//     }
+// }
+// tasks.dokkaHtmlMultiModule.configure {
+//     outputDirectory.set(buildDir.resolve("dokkaCustomMultiModuleOutput"))
+// }
+
 val ktlint: Configuration by configurations.creating
 val ktlintVersion: String by project
 dependencies {
diff --git a/client-runtime/build.gradle.kts b/client-runtime/build.gradle.kts
index 1e2a921..d2f29ff 100644
--- a/client-runtime/build.gradle.kts
+++ b/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
 }
 
diff --git a/gradle.properties b/gradle.properties
index beccec1..eb9290a 100644
--- a/gradle.properties
+++ b/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
 
diff --git a/services/build.gradle.kts b/services/build.gradle.kts
index 2a81a4a..6c83a17 100644
--- a/services/build.gradle.kts
+++ b/services/build.gradle.kts
@@ -7,6 +7,7 @@ plugins {
     kotlin("jvm")
     `maven`
     `maven-publish`
+    id("org.jetbrains.dokka")
 }
 
 val sdkVersion: String by project
@@ -22,6 +23,7 @@ subprojects {
 
     apply {
         plugin("org.jetbrains.kotlin.jvm")
+        plugin("org.jetbrains.dokka")
     }
 
     // have generated sdk's opt-in to internal runtime features
diff --git a/settings.gradle.kts b/settings.gradle.kts
index 8803ea6..a339564 100644
--- a/settings.gradle.kts
+++ b/settings.gradle.kts
@@ -12,6 +12,7 @@ pluginManagement {
     // configure the smithy-gradle plugin version
     plugins {
         id("software.amazon.smithy") version "0.5.2"
+        id("org.jetbrains.dokka") version "1.4.32"
     }
 }
 

Things I noticed right away already:

1. not sure how we'll get documentation for both aws-sdk-kotlin and smithy-kotlin runtimes and all the services into a single output. There are some open tickets on the dokka repo about supporting composite builds which might provide an answer if supported
2. the generated output will definitely need to be customized (e.g. addition of AWS logo, a front page, possibly examples or links to examples, etc)
3. I did not see the multiplatform indicators that should be there (tells you whether an api is common, jvm, js, etc)

This is a much larger task probably to get everything working, we should start small and iterate. API documentation is incredibly important so we should get it looking right.

[aajtodd]

Added a throwaway branch with what I was able to get working so far (not meant to be merged, just for demonstration):

https://github.com/awslabs/aws-sdk-kotlin/tree/docs-throwaway

./gradlew --no-daemon --no-parallel dokkaHtmlMultiModule

outputs to build/dokkaMultiModule/index.html

I haven't been able to get custom CSS that is applied on the root page to the rest of the project, seems like a bug. Also still not sure how to get smithy-kotlin included in the documentation.

There are various issues open in dokka repo of interest:

1. Suppression of RequiresOptIn API's (we probably would want to suppress documentation of @InternalSdkApi, etc)
2. Grouping the navigation tab (e.g. grouping runtime separate from services)

There is a whole lot more to explore here and build on.