AHOYAPPS-618: Publish Docs CI Integration (#76)

John Qualls · web-flow · commit 0f0ab8ec0bba · 2020-10-20T14:19:42.000-06:00
* Add dokka gradle plugin * Add property KDoc tags * Add generated Github Pages * Revert "Add generated Github Pages" This reverts commit d11c568. * Test Jekyll doc format * Revert "Test Jekyll doc format" This reverts commit bf312b0. * Change constructor documentation to match KDoc spec * Additional documenation changes to match KDoc specs * Add dokka docs * Add config.yml to use proper markdown * Revert "Add config.yml to use proper markdown" This reverts commit b32c29b. * Fixing parameter formatting * Set theme jekyll-theme-minimal * Set theme jekyll-theme-slate * Add documentation link to README * Exclude docs dir from spotless check * Change dokka config to output html to docs folder * Fix KDoc formatting * Going to store docs in another branch * Remove docs dokka output dir config * Update docs link * Add publishDocs gradle task * Fix mv command syntax * Move index.html redirect to gh-pages branch * Add publish-docs CI job * Update changelog * Move docs index.html to audioswitch modue * Reference index.html from mainline in gh-pages
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -158,6 +158,20 @@ jobs:
           command: ./gradlew incrementVersion
       - save_cache: *save_cache-gradle
 
+  publish-docs:
+    <<: *build-defaults
+    resource_class: large
+    steps:
+      - checkout
+      - attach_workspace:
+          at: *workspace
+      - restore_cache: *restore_cache-gradle
+      - run: *configure-git-user
+      - run:
+          name: Publish Docs
+          command: ./gradlew publishDocs
+      - save_cache: *save_cache-gradle
+
 workflows:
   build-test-publish:
     jobs:
@@ -187,7 +201,11 @@ workflows:
     jobs:
       - publish-release:
           <<: *release-filter
-      - bump-version:
+      - publish-docs:
           <<: *release-filter
           requires:
             - publish-release
+      - bump-version:
+          <<: *release-filter
+          requires:
+            - publish-docs
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,11 @@
 # Changelog
 
+### 1.1.1
+
+Enhancements
+
+- Added public KDoc documentation for each release. The latest documentation release can be found at https://twilio.github.io/audioswitch/latest
+
 ### 1.1.0
 
 Enhancements
diff --git a/README.md b/README.md
@@ -20,6 +20,10 @@ Android Studio Version | Android API Version Min
 ------------ | -------------
 3.6+ | 16
 
+## Documentation
+
+The KDoc for this library can be found [here](https://twilio.github.io/audioswitch/latest).
+
 ## Getting Started
 
 To get started using this library, follow the steps below.
diff --git a/audioswitch/build.gradle b/audioswitch/build.gradle
@@ -3,6 +3,7 @@ apply plugin: 'maven'
 apply plugin: 'maven-publish'
 apply plugin: "com.jfrog.artifactory"
 apply plugin: 'kotlin-android'
+apply plugin: "org.jetbrains.dokka"
 
 android {
     compileSdkVersion 30
@@ -37,6 +38,16 @@ android {
         }
     }
 
+    dokkaHtml.configure {
+        dokkaSourceSets {
+            named("main") {
+                noAndroidSdkLink.set(false)
+                includeNonPublic = false
+                reportUndocumented = true
+                skipEmptyPackages = true
+            }
+        }
+    }
 }
 
 dependencies {
diff --git a/audioswitch/index.html b/audioswitch/index.html
@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Document</title>
+</head>
+<body>
+<script>
+    window.location.replace(document.location.href + "audioswitch/index.html");
+  </script>
+</body>
+</html>
diff --git a/audioswitch/src/main/java/com/twilio/audioswitch/AudioDeviceChangeListener.kt b/audioswitch/src/main/java/com/twilio/audioswitch/AudioDeviceChangeListener.kt
@@ -1,11 +1,10 @@
 package com.twilio.audioswitch
 
-/** A listener that receives the most recently available [AudioDevice]s.
+/**
  * Receives a list of the most recently available [AudioDevice]s. Also provides the
  * currently selected [AudioDevice] from [AudioSwitch].
- *
- * @param audioDevices the list of [AudioDevice]s or an empty list if none are available.
- * @param selectedAudioDevice the currently selected device or null if no device has been selected.
+ * - audioDevices - The list of [AudioDevice]s or an empty list if none are available.
+ * - selectedAudioDevice - The currently selected device or null if no device has been selected.
  */
 typealias AudioDeviceChangeListener = (
     audioDevices: List<AudioDevice>,
diff --git a/audioswitch/src/main/java/com/twilio/audioswitch/AudioSwitch.kt b/audioswitch/src/main/java/com/twilio/audioswitch/AudioSwitch.kt
@@ -26,7 +26,12 @@ private const val TAG = "AudioSwitch"
  * should be routed to. It is strongly recommended that instances of this class are created and
  * accessed from a single application thread. Accessing an instance from multiple threads may cause
  * synchronization problems.
- */
+ *
+ * @property loggingEnabled A property to configure AudioSwitch logging behavior. AudioSwitch logging is disabled by
+ * default.
+ * @property selectedAudioDevice Retrieves the selected [AudioDevice] from [AudioSwitch.selectDevice].
+ * @property availableAudioDevices Retrieves the current list of available [AudioDevice]s.
+**/
 class AudioSwitch {
 
     private var logger: Logger = ProductionLogger()
@@ -67,58 +72,30 @@ class AudioSwitch {
         }
     }
 
-    /**
-     * A property to configure AudioSwitch logging behavior. AudioSwitch logging is disabled by
-     * default.
-     */
     var loggingEnabled: Boolean
-        /**
-         * Returns `true` if logging is enabled. Returns `false` by default.
-         */
         get() = logger.loggingEnabled
 
-        /**
-         * Toggle whether logging is enabled.
-         */
         set(value) {
             logger.loggingEnabled = value
         }
-
-    /**
-     * Retrieves the selected [AudioDevice] from [AudioSwitch.selectDevice].
-     *
-     * @return the selected [AudioDevice]
-     */
     val selectedAudioDevice: AudioDevice? get() = selectedDevice
-
-    /**
-     * Retrieves the current list of available [AudioDevice]s.
-     *
-     * @return the current list of [AudioDevice]s
-     */
     val availableAudioDevices: List<AudioDevice> = mutableAudioDevices
 
     /**
      * Constructs a new AudioSwitch instance.
-     *
-     * @param context An Android Context.
-     * @param loggingEnabled Toggle whether logging is enabled. This argument is false by default.
-     * @param audioFocusChangeListener A listener that is invoked when the system audio focus is updated.
+     * - [context] - An Android Context.
+     * - [loggingEnabled] - Toggle whether logging is enabled. This argument is false by default.
+     * - [audioFocusChangeListener] - A listener that is invoked when the system audio focus is updated.
      * Note that updates are only sent to the listener after [activate] has been called.
-     * @param preferredDeviceList The order in which [AudioSwitch] automatically selects and activates
+     * - [preferredDeviceList] - The order in which [AudioSwitch] automatically selects and activates
      * an [AudioDevice]. This parameter is ignored if the [selectedAudioDevice] is not `null`.
-     *
      * The default preferred [AudioDevice] order is the following:
-     *
      * [BluetoothHeadset], [WiredHeadset], [Earpiece], [Speakerphone]
-     *
-     * [preferredDeviceList] is added to the front of the default list. For example, if [preferredDeviceList]
+     * . The [preferredDeviceList] is added to the front of the default list. For example, if [preferredDeviceList]
      * is [Speakerphone] and [BluetoothHeadset], then the new preferred audio
      * device list will be:
-     *
      * [Speakerphone], [BluetoothHeadset], [WiredHeadset], [Earpiece].
-     *
-     * @throws IllegalArgumentException if the [preferredDeviceList] contains duplicate [AudioDevice] elements.
+     * An [IllegalArgumentException] is thrown if the [preferredDeviceList] contains duplicate [AudioDevice] elements.
      */
     @JvmOverloads
     constructor(
@@ -171,11 +148,9 @@ class AudioSwitch {
     }
 
     /**
-     * Starts listening for audio device changes. **Note:** When audio device listening is no
-     * longer needed, [AudioSwitch.stop] should be called in order to prevent a
-     * memory leak.
-     *
-     * @param listener receives audio device change events
+     * Starts listening for audio device changes and calls the [listener] upon each change.
+     * **Note:** When audio device listening is no longer needed, [AudioSwitch.stop] should be
+     * called in order to prevent a memory leak.
      */
     fun start(listener: AudioDeviceChangeListener) {
         audioDeviceChangeListener = listener
@@ -253,11 +228,10 @@ class AudioSwitch {
     }
 
     /**
-     * Selects the desired [AudioDevice]. If the provided [AudioDevice] is not
-     * available, no changes are made. If the provided [AudioDevice] is null, an [AudioDevice] is
-     * chosen based on the following preference: Bluetooth, Wired Headset, Earpiece, Speakerphone.
-     *
-     * @param audioDevice The [AudioDevice] to use
+     * Selects the desired [audioDevice]. If the provided [AudioDevice] is not
+     * available, no changes are made. If the provided device is null, one is chosen based on the
+     * specified preferred device list or the following default list:
+     * [BluetoothHeadset], [WiredHeadset], [Earpiece], [Speakerphone].
      */
     fun selectDevice(audioDevice: AudioDevice?) {
         if (selectedDevice != audioDevice) {
diff --git a/build.gradle b/build.gradle
@@ -1,5 +1,6 @@
 buildscript {
     ext.kotlin_version = '1.4.0'
+    ext.dokka_version = '1.4.10'
 
     /**
      * Properties and environment variables needed to publish to Bintray.
@@ -74,17 +75,20 @@ buildscript {
     dependencies {
         classpath 'com.android.tools.build:gradle:4.0.0'
         classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+        classpath "org.jetbrains.dokka:dokka-gradle-plugin:$dokka_version"
     }
 }
 
 plugins {
     id "com.diffplug.spotless" version "5.6.1"
     id "com.jfrog.artifactory" version "4.15.2"
+    id "org.jetbrains.dokka" version "1.4.10"
 }
 apply plugin: "com.diffplug.spotless"
 spotless {
     format 'misc', {
         target '**/*.gradle', '**/*.md', '**/.gitignore'
+        targetExclude 'docs/**'
 
         trimTrailingWhitespace()
         indentWithSpaces()
@@ -238,3 +242,85 @@ task bintrayAudioSwitchReleaseUpload(type: RootGradleBuild) {
             'maven.password': "${getPropertyValue("AUDIOSWITCH_BINTRAY_PASSWORD")}"
     ]
 }
+
+task publishDocs {
+    description = 'Publish AudioSwitch KDocs to gh-pages branch'
+    group = 'Publishing'
+    dependsOn 'audioswitch:dokkaHtml'
+    dependsOn validateReleaseTag
+    def releaseVersion = System.getenv("CIRCLE_TAG") == null ?
+            ("") :
+            (System.getenv("CIRCLE_TAG"))
+    def pinLatestDocsCommand = ["ln", "-sfn", "${releaseVersion}", "docs/latest"]
+    def githubToken = System.getenv("GITHUB_TOKEN")
+    def repoSlug = "${System.env.CIRCLE_PROJECT_USERNAME}/${System.env.CIRCLE_PROJECT_REPONAME}"
+    def gitRef = "https://${githubToken}@github.com/${repoSlug}.git"
+    def remote = "upstream"
+    def pushNullFile = new FileOutputStream("/dev/null")
+
+    doLast {
+        exec {
+            workingDir "${rootDir}"
+            commandLine "cp", "audioswitch/index.html", "audioswitch/build"
+        }
+
+        exec {
+            workingDir "${rootDir}"
+            commandLine "git", "remote", "add", "${remote}", "${gitRef}"
+            // Ignore exit value because remote may have been added in previous task
+            ignoreExitValue true
+        }
+
+        exec {
+            workingDir "${rootDir}"
+            commandLine "git", "fetch", "${remote}"
+        }
+
+        exec {
+            workingDir "${rootDir}"
+            commandLine "git", "checkout", "-b", "gh-pages", "remotes/${remote}/gh-pages"
+        }
+
+        exec {
+            workingDir "${rootDir}"
+            commandLine "mkdir", "docs"
+            ignoreExitValue true
+        }
+
+        exec {
+            workingDir "${rootDir}"
+            commandLine "cp", "-r", "audioswitch/build/dokka/html/.", "docs/${releaseVersion}"
+        }
+
+        exec {
+            workingDir "${rootDir}"
+            commandLine "cp", "audioswitch/build/index.html", "docs/${releaseVersion}"
+        }
+
+        exec {
+            workingDir "${rootDir}"
+            commandLine pinLatestDocsCommand
+        }
+
+        exec {
+            workingDir "${rootDir}"
+            commandLine "git", "add", "docs/${releaseVersion}", "docs/latest"
+        }
+
+        exec {
+            workingDir "${rootDir}"
+            commandLine "git", "commit", "-m", "\"${releaseVersion} release docs [skip ci]\""
+        }
+
+        exec {
+            workingDir "${rootDir}"
+            commandLine "git", "push", "--quiet", "${remote}", "gh-pages"
+            standardOutput pushNullFile
+        }
+
+        exec {
+            workingDir "${rootDir}"
+            commandLine "git", "checkout", "${releaseVersion}"
+        }
+    }
+}
