update Dokka to 1.7.20 and add source links

fixes #124

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,48 @@ 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(
+            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 +129,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"))
 }

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.