Merge pull request #38 from arunkumar9t2/chore/update-documentation

0.2.0 and documentation update

README.md

@@ -27,6 +27,10 @@ width="210" hspace="10" vspace="10">
 <img src="https://thumbs.gfycat.com/ThankfulConfusedKillifish-small.gif">
 </p>
 
+<p align="center">
+<img src="docs/images/dev.arunkumar.scabbard.coffee.CoffeeApp.CoffeeShop.svg">
+</p>
+
 More advanced [examples](https://arunkumar9t2.github.io/scabbard/examples/).
 
 ## Features

build.gradle

@@ -28,15 +28,16 @@ task clean(type: Delete) {
 }
 
 def isWin = System.getProperty("os.name").toLowerCase().contains("win")
+def samplePath = "samples:android-kotlin"
+def sampleProject = project(samplePath)
 
 //TODO Investigate migrating to GradleBuild. ATM has issues disabling daemon.
 tasks.register("runScabbardProcessor" /*, GradleBuild*/) {
     group = "development"
-    def sample = "samples:android-kotlin"
     doLast {
         def isDebug = project.hasProperty("debug")
         if (isDebug) {
-            delete fileTree("${sample}/build").matching {
+            delete fileTree(sampleProject.buildDir).matching {
                 include "**/*.dot"
                 include "**/*.png"
             }
@@ -48,7 +49,7 @@ tasks.register("runScabbardProcessor" /*, GradleBuild*/) {
 
             def gradleDebug = "-Dorg.gradle.debug=$isDebug"
             def daemon = isDebug ? '--no-daemon' : ''
-            def command = "${commandPrefix}gradlew $daemon $gradleDebug ${sample}:kaptDebugKotlin"
+            def command = "${commandPrefix}gradlew $daemon $gradleDebug ${samplePath}:kaptDebugKotlin"
             workingDir(projectDir)
             commandLine shell, shellArg, command
         }
@@ -67,4 +68,33 @@ tasks.register("docsServe") {
         }
         exec { commandLine("mkdocs", "serve") }
     }
-}
+}
+
+tasks.register("publishSampleImages") {
+    group = "documentation"
+    description = "Publishes sample images to website"
+    doLast {
+        copy {
+            from "${sampleProject.buildDir}/tmp/kapt3/classes/debug/scabbard"
+            include "*.svg"
+            exclude "full_*.svg"
+            into "docs/images"
+        }
+    }
+    dependsOn sampleProject.tasks.named("kaptDebugKotlin")
+}
+
+// Common publish task to publish all artifacts
+tasks.register("publishAllArtifacts") {
+    group = "publishing"
+    description = "Publishes all artifiacts"
+    doFirst {
+        logger.quiet("Publishing version $publishVersion")
+    }
+    dependsOn project("scabbard-idea-plugin").tasks.named("publishPlugin")
+    dependsOn gradle.includedBuild("scabbard-gradle-plugin").task(":publishPlugins")
+    dependsOn project("scabbard-processor").tasks.named("bintrayUpload")
+    doLast {
+        logger.quiet("Done!")
+    }
+}

constants.gradle

@@ -23,6 +23,6 @@ ext {
 
     groupId = 'dev.arunkumar'
     scabbardGradlePlugin = 'scabbard.gradle'
-    publishVersion = '0.1.0'
+    publishVersion = '0.2.0'
     website = 'https://github.com/arunkumar9t2/scabbard'
 }

docs/cheat-sheet.md

@@ -2,4 +2,4 @@
 
 Below is the base graph from `scabbard-sample` which contains all types of bindings. A better version of cheet sheet is planned.
 
-<img src="../images/temp-cheat-sheat.png" width="100%">
+<a href="../images/dev.arunkumar.scabbard.di.AppComponent.svg"><img src="../images/dev.arunkumar.scabbard.di.AppComponent.svg" width="100%"></a>

docs/configuration.md

@@ -2,34 +2,43 @@
 
 ## Gradle plugin
 
-The `scabbard` plugin can be configured in following ways.
+The `scabbard` plugin can be configured in following ways and is the entry point for customizing scabbard processor behavior.
+
+!!! tip "What's new"
+    Recent additions include support for [simple names](#qualified-names), [SVG output format](#output-format) and easier setup for [multi-module projects](#multi-module-projects).
+
+!!! example "Configuration Examples"
+    Example gradle build script configurations.
+
+    * [Android Kotlin project](https://github.com/arunkumar9t2/scabbard/blob/master/samples/android-kotlin/build.gradle)
+    * [Java library project with KTS build script](https://github.com/arunkumar9t2/scabbard/blob/master/samples/java-library-kts-script/build.gradle.kts)
 
 ### Enable scabbard processor
 
 ```Groovy tab=
 scabbard {
-    enabled true // default true
+  enabled true // default false
 }
 ```
 
 ```Kotlin tab=
-scabbard.configure(closureOf<ScabbardSpec> {
-    enabled(true) // default true
-})
+scabbard {
+  enabled = true // default false
+}
 ```
 
 ### Fail build on any error in Scabbard processor
 
 ```Groovy tab=
 scabbard {
-    failOnError true // default false
+  failOnError true // default false
 }
 ```
 
 ```Kotlin tab=
-scabbard.configure(closureOf<ScabbardSpec> {
-    failOnError(true) // default false
-})
+scabbard {
+  failOnError = true // default false
+}
 ```
 
 By default, Scabbard processor does not fail the build should any error occur. This flag could be used to change that behavior.
@@ -38,18 +47,74 @@ By default, Scabbard processor does not fail the build should any error occur. T
 
 ```Groovy tab=
 scabbard {
-    fullBindingGraphValidation true // default false
+  fullBindingGraphValidation true // default false
 }
 ```
 
 ```Kotlin tab=
-scabbard.configure(closureOf<ScabbardSpec> {
-    fullBindingGraphValidation(true) // default false
-})
+scabbard {
+  fullBindingGraphValidation = true // default false
+}
 ```
 
 Enables Dagger's [full binding graph validation](https://dagger.dev/compiler-options.html#full-binding-graph-validation) which validates the entire graph including all bindings in every `@Component`, `@Subcomponent` and `@Module`. This enables highlighting missing bindings which can be used to understand errors. Additionally since `@Module` itself is seen a graph, graphs will be generated for bindings in a `@Module`.
 
+### Qualified Names
+
+Since `0.2.0`, Scabbard uses simple names in graph images to keep the graph short. The qualified names behaviour could be restored as follows.
+
+```Groovy tab=
+scabbard {
+  qualifiedNames true // default false
+}
+```
+
+```Kotlin tab=
+scabbard {
+  qualifiedNames = true // default false
+}
+```
+
+### Output format
+
+Supported output formats for generated images are `png` and `svg`.
+
+```Groovy tab=
+scabbard {
+  outputFormat "png" // default png
+}
+```
+
+```Kotlin tab=
+scabbard {
+  outputFormat = "svg" // default png
+}
+```
+
 ### Multi-module projects
 
-While in most cases, applying on `app` module is sufficient, depending on your project structure, you might need to apply Scabbard gradle plugin wherever Dagger compiler is applied.
+For multi-module projects, it is sufficient to apply Scabbard plugin in root project's `build.gradle` file. Doing so will let the plugin configure all subprojects for graph generation. 
+
+In root `build.gradle` file:
+
+```Groovy tab=
+apply plugin: "scabbard.gradle"
+
+scabbard {
+  enabled true
+  failOnError true
+  fullBindingGraphValidation true
+  outputFormat "svg"
+}
+```
+
+```Kotlin tab=
+apply(plugin = "scabbard.gradle")
+
+scabbard {
+  enabled = true
+  failOnError = false
+  fullBindingGraphValidation = false
+  outputFormat = "svg"
+}
+```

docs/contributing.MD

@@ -4,10 +4,10 @@ If you would like to contribute to Scabbard you can do so through GitHub by fork
 
 ## Running Scabbard locally
 
-After the cloning the repo, the project could be built by `.gradlew assemble` command. Scabbard also ships with IDE configurations for common tasks.
+After the cloning the repo, the project could be built by `./gradlew assemble` command. Scabbard also ships with IDE configurations for common tasks.
 
-* `runScabbardProcessor` - Runs the annotation processor on `scabbard-sample` project. After build, graphs should have been generated.
-* `debugScabbardProcessor` - Starts a gradle build for debugging and waits for debugger to be attached. Please run `Attach Scabbard Debugger` config to attach the debugger. Breakpoints and step through should work normally.
+* `Run Scabbard Processor` - Runs the annotation processor on `samples:android-kotlin` project. After build, graphs should have generated.
+* `Debug Scabbard Processor` - Starts a gradle build for debugging and waits for debugger to be attached. Please run `Attach Scabbard Debugger` config to attach the debugger. Breakpoints and step through should work normally.
 * `Run Scabbard IntelliJ Plugin` - Builds the plugin and opens an IntelliJ instance that has the plugin applied.
 
 ## Workflow

docs/examples.md

@@ -2,28 +2,32 @@
 
 Please download/open in new tab to zoom contents.
 
+## [Coffee App from Dagger](https://github.com/google/dagger/tree/master/examples/simple/src/main/java/coffee)
+
+<a href="../images/dev.arunkumar.scabbard.coffee.CoffeeApp.CoffeeShop.svg"><img src="../images/dev.arunkumar.scabbard.coffee.CoffeeApp.CoffeeShop.svg" width="100%"></a>
+
 ## [Google I/O 2019 App](https://github.com/google/iosched)
 
 <video width="100%" controls>
   <source src="../video/iosched_appcomponent.mp4" type="video/mp4">
   Your browser does not support the video tag.
 </video>
 
-`AppComponent`
-<img src="../images/io_appcomponent.png" width="100%">
+### `AppComponent`
+<a href="../images/com.google.samples.apps.iosched.di.AppComponent.svg"><img src="../images/com.google.samples.apps.iosched.di.AppComponent.svg" width="100%"></a>
 
-`MainActivitySubComponent`
-<img src="../images/io_main.png" width="100%">
+### `MainActivitySubComponent`
+<a href="../images/com.google.samples.apps.iosched.di.ActivityBindingModule_MainActivity.mobile_debug.MainActivitySubcomponent.svg"><img src="../images/com.google.samples.apps.iosched.di.ActivityBindingModule_MainActivity.mobile_debug.MainActivitySubcomponent.svg" width="100%"></a>
 
-## [Plaid](https://github.com/android/plaid)
+## [Santa Tracker](https://github.com/google/santa-tracker-android)
 
-`HomeComponent`
-<img src="../images/plaid_home.png" width="100%">
+### `AppComponent`
+<a href="../images/com.google.android.apps.santatracker.di.AppComponent.svg"><img src="../images/com.google.android.apps.santatracker.di.AppComponent.svg" width="100%"></a>
 
-`UpvoteStoryServiceComponent`
-<img src="../images/plaid_upvote.png" width="100%">
+## [Plaid](https://github.com/android/plaid)
 
-## [Santa Tracker](https://github.com/google/santa-tracker-android)
+### `HomeComponent`
+<a href="../images/io.plaidapp.dagger.HomeComponent.svg"><img src="../images/io.plaidapp.dagger.HomeComponent.svg" width="100%"></a>
 
-`AppComponent`
-<img src="../images/santatracker_appcomponent.png" width="100%">
+### `UpvoteStoryServiceComponent`
+<a href="../images/io.plaidapp.core.dagger.designernews.UpvoteStoryServiceComponent.svg"><img src="../images/io.plaidapp.core.dagger.designernews.UpvoteStoryServiceComponent.svg" width="100%"></a>

docs/faq.md

@@ -10,6 +10,14 @@ Yes.
 
 There should be no impact since Scabbard only runs during compilation and generated images are not meant to be packaged into binary. You could control if Scabbard is enabled for release builds via `scabbard { enabled = false }` block.
 
+!!! tip
+    For Android, one way to disable Scabbard for release builds is by simply flipping the `enabled` property in Gradle plugin extension as follows.
+    ```groovy
+    scabbard {
+      enabled !gradle.startParameter.toString().contains("assembleRelease")
+    }
+    ```
+
 ## What is the impact on build time?
 
 1. Scabbard processor uses standard annotation processing APIs to generate images. This lets the processor be cacheable and does not run when inputs have not changed.
@@ -20,13 +28,17 @@ There should be no impact since Scabbard only runs during compilation and genera
 
 Please refer to Scabbard [cheat sheet](cheat-sheet.md).
 
-## Will more formats (svg) be supported?
-
-Yes, there are plans to support more formats. Please 👍 this [issue](https://github.com/arunkumar9t2/scabbard/issues/8).
 
 ## I don't see gutter icons to view graph.
 
-Please wait for Android Studio/IntelliJ indexing to be done for gutter icons to be visible. Even after indexing if the icons are not visible, please file an issue. You could also look for generated `png` file in the `build` folder.
+Please wait for Android Studio/IntelliJ indexing to be done for gutter icons to be visible. Even after indexing if the icons are not visible, please file an issue.
+
+The common causes for missing gutter icons are
+
+*  Images are generated but IntelliJ index cache is corrupted. Please try `Invalidate Cache and Restart` to reindex the files.
+*  Image are not generated. Please enable `scabbard.failOnError` and observe Gradle build log for any errors.
+
+You could also manually look for generated images in the `build` folder as described [here](index.md#gradle-plugin).
 
 ## Some dependencies are missing.