Merge pull request #893 from square/rick/dokka_links

update Dokka to 1.7.20, switch `siteDokka` to html, and add source links

build.gradle.kts

@@ -1,5 +1,6 @@
 import com.squareup.workflow1.buildsrc.applyKtLint
-import org.jetbrains.dokka.gradle.DokkaTask
+import org.jetbrains.dokka.gradle.AbstractDokkaLeafTask
+import java.net.URL
 
 buildscript {
   dependencies {
@@ -50,14 +51,49 @@ apply(plugin = "org.jetbrains.dokka")
 // Configuration that applies to all dokka tasks, both those used for generating javadoc artifacts
 // and the documentation site.
 subprojects {
-  tasks.withType<DokkaTask>().configureEach {
+  tasks.withType<AbstractDokkaLeafTask> {
+
+    // This is the displayed name for the module, like in the Html sidebar.
+    //   artifact id: workflow-internal-testing-utils
+    //          path: internal-testing-utils
+    moduleName.set(
+      provider {
+        findProperty("POM_ARTIFACT_ID") as? String
+          ?: project.path.removePrefix(":")
+      }
+    )
+
     dokkaSourceSets.configureEach {
+
+      val dokkaSourceSet = this
+
       reportUndocumented.set(false)
       skipDeprecated.set(true)
-      jdkVersion.set(8)
-
-      // TODO(#124) Add source links.
 
+      if (file("src/${dokkaSourceSet.name}").exists()) {
+
+        val readmeFile = file("$projectDir/README.md")
+        // If the module has a README, add it to the the module's index
+        if (readmeFile.exists()) {
+          includes.from(readmeFile)
+        }
+
+        sourceLink {
+          localDirectory.set(file("src/${dokkaSourceSet.name}"))
+
+          val modulePath = projectDir.relativeTo(rootDir).path
+
+          // URL showing where the source code can be accessed through the web browser
+          remoteUrl.set(
+            @Suppress("ktlint:max-line-length")
+            URL(
+              "https://github.com/square/workflow-kotlin/blob/main/$modulePath/src/${dokkaSourceSet.name}"
+            )
+          )
+          // Suffix which is used to append the line number to the URL. Use #L for GitHub
+          remoteLineSuffix.set("#L")
+        }
+      }
       perPackageOption {
         // Will match all .internal packages and sub-packages, regardless of module.
         matchingRegex.set(""".*\.internal.*""")
@@ -94,13 +130,13 @@ allprojects {
 // name and destination directory are defined in this script:
 // https://github.com/square/workflow/blob/main/deploy_website.sh
 tasks.register<Copy>("siteDokka") {
-  description = "Generate dokka Github-flavored Markdown for the documentation site."
+  description = "Generate dokka Html for the documentation site."
   group = "documentation"
-  dependsOn(":dokkaGfmCollector")
+  dependsOn(":dokkaHtmlMultiModule")
 
   // Copy the files instead of configuring a different output directory on the dokka task itself
   // since the default output directories disambiguate between different types of outputs, and our
   // custom directory doesn't.
-  from(buildDir.resolve("dokka/gfmCollector/workflow"))
+  from(buildDir.resolve("dokka/htmlMultiModule/workflow"))
   into(buildDir.resolve("dokka/workflow"))
 }

dependencies/classpath.txt

@@ -37,13 +37,13 @@ com.android.tools:sdk-common:30.3.0
 com.android.tools:sdklib:30.3.0
 com.android:signflinger:7.3.0
 com.android:zipflinger:7.3.0
-com.fasterxml.jackson.core:jackson-annotations:2.12.4
-com.fasterxml.jackson.core:jackson-core:2.12.4
-com.fasterxml.jackson.core:jackson-databind:2.12.4
-com.fasterxml.jackson.dataformat:jackson-dataformat-xml:2.12.4
-com.fasterxml.jackson.module:jackson-module-jaxb-annotations:2.12.4
-com.fasterxml.jackson.module:jackson-module-kotlin:2.12.4
-com.fasterxml.jackson:jackson-bom:2.12.4
+com.fasterxml.jackson.core:jackson-annotations:2.12.7
+com.fasterxml.jackson.core:jackson-core:2.12.7
+com.fasterxml.jackson.core:jackson-databind:2.12.7
+com.fasterxml.jackson.dataformat:jackson-dataformat-xml:2.12.7
+com.fasterxml.jackson.module:jackson-module-jaxb-annotations:2.12.7
+com.fasterxml.jackson.module:jackson-module-kotlin:2.12.7
+com.fasterxml.jackson:jackson-bom:2.12.7
 com.fasterxml.woodstox:woodstox-core:6.2.4
 com.github.gundy:semver4j:0.16.4
 com.google.android:annotations:4.1.1.4
@@ -126,8 +126,8 @@ org.codehaus.woodstox:stax2-api:4.2.1
 org.glassfish.jaxb:jaxb-runtime:2.3.2
 org.glassfish.jaxb:txw2:2.3.2
 org.jdom:jdom2:2.0.6
-org.jetbrains.dokka:dokka-core:1.5.31
-org.jetbrains.dokka:dokka-gradle-plugin:1.5.31
+org.jetbrains.dokka:dokka-core:1.7.20
+org.jetbrains.dokka:dokka-gradle-plugin:1.7.20
 org.jetbrains.intellij.deps:trove4j:1.0.20200330
 org.jetbrains.kotlin:kotlin-android-extensions:1.7.10
 org.jetbrains.kotlin:kotlin-annotation-processing-gradle:1.7.10
@@ -160,14 +160,15 @@ org.jetbrains.kotlin:kotlin-util-klib-metadata:1.6.0
 org.jetbrains.kotlin:kotlin-util-klib:1.7.10
 org.jetbrains.kotlinx:binary-compatibility-validator:0.11.1
 org.jetbrains.kotlinx:kotlinx-benchmark-plugin:0.4.2
-org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:1.5.1
-org.jetbrains.kotlinx:kotlinx-coroutines-core:1.5.1
+org.jetbrains.kotlinx:kotlinx-coroutines-bom:1.6.3
+org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:1.6.3
+org.jetbrains.kotlinx:kotlinx-coroutines-core:1.6.3
 org.jetbrains.kotlinx:kotlinx-metadata-jvm:0.5.0
 org.jetbrains:annotations:13.0
-org.jetbrains:markdown-jvm:0.2.4
-org.jetbrains:markdown:0.2.4
+org.jetbrains:markdown-jvm:0.3.1
+org.jetbrains:markdown:0.3.1
 org.json:json:20180813
-org.jsoup:jsoup:1.13.1
+org.jsoup:jsoup:1.14.3
 org.jvnet.staxex:stax-ex:1.8.1
 org.openjdk.jmh:jmh-core:1.21
 org.ow2.asm:asm-analysis:9.1

gradle/libs.versions.toml

@@ -34,7 +34,7 @@ androidx-viewbinding = "4.2.1"
 androidx-work = "2.6.0"
 
 detekt = "1.19.0"
-dokka = "1.5.31"
+dokka = "1.7.20"
 dependencyGuard = "0.1.0"
 
 google-accompanist = "0.18.0"

trace-encoder/README.md

@@ -1,4 +1,4 @@
-# trace-encoder
+# Module trace-encoder
 
 This module contains a small library for generating trace files that can be viewed with Chrome by
 visiting `chrome://tracing`. Trace events are represented by the various subclasses of `TraceEvent`,

workflow-core/README.md

@@ -1,4 +1,4 @@
-# workflow-core
+# Module workflow-core
 
 This module contains the core workflow APIs.
 

workflow-runtime/README.md

@@ -1,3 +1,3 @@
-# workflow-runtime
+# Module workflow-runtime
 
 This module contains the core APIs and logic for running workflows.

workflow-rx2/README.md

@@ -1,3 +1,3 @@
-# workflow-rx2
+# Module workflow-rx2
 
 This module contains adapters to use Workflows with RxJava2.

workflow-testing/README.md

@@ -1,3 +1,3 @@
-# workflow-testing
+# Module workflow-testing
 
 This module contains APIs for testing workflows.

workflow-tracing/README.md

@@ -1,4 +1,4 @@
-# workflow-tracing
+# Module workflow-tracing
 
 This module provides a `WorkflowDiagnosticListener` called `TracingDiagnosticListener` that can be
 plugged into a `WorkflowSession` to generate a Chrome-viewable tracing file. For more information

workflow-ui/compose-tooling/README.md

@@ -1,3 +1,3 @@
-# compose-tooling
+# Module compose-tooling
 
 TODO

workflow-ui/compose/README.md

@@ -1,4 +1,4 @@
-# compose
+# Module compose
 
 This module hosts the workflow-ui compose integration, and this file describes in detail how that integration works and why.
 It was originally published as a [blog post](https://developer.squareup.com/blog/jetpack-compose-support-in-workflow).

workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/container/ViewStateCache.kt

@@ -59,16 +59,16 @@ internal constructor(
    * associated view state will be retained in the cache, possibly to be restored to [newView]
    * on a succeeding call to his method. Any other cached view state will be dropped.
    *
-   * @param oldViewMaybe the view that is being removed, if any, which is expected to be showing
+   * @param oldHolderMaybe the view that is being removed, if any, which is expected to be showing
    * a [NamedScreen] rendering. If that rendering is
    * [compatible with][com.squareup.workflow1.ui.compatible] a member of
    * [retainedRenderings], its state will be [saved][View.saveHierarchyState].
    *
-   * @param newView the view that is about to be displayed, which must be showing a
+   * @param newHolder the view that is about to be displayed, which must be showing a
    * [NamedScreen] rendering. If [compatible][com.squareup.workflow1.ui.compatible]
    * view state is found in the cache, it is [restored][View.restoreHierarchyState].
    *
-   * @return true if [newView] has been restored.
+   * @return true if [newHolder] has been restored.
    */
   public fun update(
     retainedRenderings: Collection<NamedScreen<*>>,

workflow-ui/radiography/README.md

@@ -1,4 +1,4 @@
-# radiography
+# Module radiography
 
 This module provides support for configuring [Radiography](https://github.com/square/radiography)
 to show more helpful information about views created by workflow view factories.