Merge branch 'documentation-fixes' into 'master'

Update documentation

See merge request mobile/grazel!96

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,6 @@
+## Proposed Changes
+
+## Testing
+<!--- Please describe how you tested your changes. -->
+
+## Issues Fixed

README.MD

@@ -1,6 +1,17 @@
 # Grazel
 
-**Grazel** stands for `Gradle` to `Bazel`. It is a Gradle plugin that enables you to migrate Android projects to [Bazel build](https://bazel.build) system in an incremental and automated fashion. 
+**Grazel** stands for `Gradle` to `Bazel`. A Gradle plugin to migrate Android projects to [Bazel build](https://bazel.build) system in an incremental and automated fashion. 
+
+<p align="center"> 
+<a href="https://github.com/grab/Grazel/releases/latest"><img src="https://img.shields.io/github/release/grab/Grazel.svg?style=flat-square&label=Release&logo=github&colorB=00bdd6"/></a>
+<img alt="Maven Central" src="https://img.shields.io/maven-central/v/com.grab.grazel/grazel-gradle-plugin?logo=apache-maven&logoColor=%23C71A36&style=flat-square&colorB=00bdd6">
+<img src="https://img.shields.io/github/workflow/status/arunkumar9t2/scabbard/Build%20Workflow?style=flat-square&logo=github">
+<a href="https://grab.github.io/Grazel/"><img src="https://img.shields.io/badge/Website-%20-lightgrey.svg?color=00bdd6&colorA=00bdd6&style=flat-square&logo=github"/></a>
+</p>
+
+<p align="center">
+<img src="docs/images/grazel-demo.gif" width="85%">
+</p>
 
 ## Components
 
@@ -11,7 +22,7 @@
 ## Features
 
 * Generate `BUILD.bazel`, `WORKSPACE` for given Android project and reduce the overall migration effort.
-* Setup hybrid build to build part of project graph to build with Bazel and rest with Gradle.
+* Setup [hybrid build](https://grab.github.io/Grazel/hybrid_builds/) to build part of project graph to build with Bazel and rest with Gradle.
 * Minimal source changes to codebase - supported by [Grab Bazel Common](https://github.com/grab/grab-bazel-common).
 * Gradle Configuration as source of truth.
 
@@ -29,7 +40,6 @@ apply plugin: "kotlin-android"
 
 android {
     compileSdkVersion rootProject.compileSdk
-
     defaultConfig {
         minSdkVersion rootProject.minSdk
         targetSdkVersion rootProject.targetSdk
@@ -69,11 +79,14 @@ kt_android_library(
         "@maven//:androidx_test_espresso_espresso_idling_resource",
     ],
 )
-
 ```
 
 See [migration capabilities](https://grab.github.io/Grazel/migration_capabilities) for supported features. In advanced cases, where entire project might not be [migratable](https://grab.github.io/Grazel/migration_criteria), it migrates part of the graph and sets up [hybrid build](https://grab.github.io/Grazel/hybrid_builds) where part of the graph can be built with Bazel and rest with Gradle.
 
+## Resources
+
+* [Grab's migration journey from Gradle to Bazel via automation](https://www.youtube.com/watch?v=VMkjZAI_sN8) - Build Meetup'21.
+
 ## License
 
 ```

docs/databinding.md

@@ -1,3 +1,24 @@
 # Kotlin Databinding Support
 
-TBA
+Databinding support, especially with Kotlin is an ongoing effort. See [issue](https://github.com/bazelbuild/bazel/issues/2694) for details.
+
+In order to compile Kotlin based Gradle module that uses databinding without much refactors, Grazel uses custom `kt_db_android_library` rules from [grab-bazel-common](https://github.com/grab/grab-bazel-common). See [databinding.bzl](https://github.com/grab/grab-bazel-common/blob/5076af89a1c0fd56f11a09b42eee5e6aa017dd73/tools/databinding/databinding.bzl#L159) for more details.
+
+Additionally, Grazel employs few [custom patches](https://github.com/grab/grab-bazel-common/tree/master/patches) to Bazel's Android Tools jar for performance and build fixes.
+
+By default, the patched tools are imported to current build via `android_tools` macro in `WORKSPACE`. 
+
+```python
+load("@grab_bazel_common//:workspace_defs.bzl", "android_tools")
+
+android_tools(
+    commit = "f74ef90479383a38cef1af33d28a3253031e00c1",
+    remote = "https://github.com/grab/grab-bazel-common.git",
+)
+```
+
+Commenting out `android_tools` will use the Android tools version shipped with Bazel.
+
+Supported features:
+
+* TBA

docs/index.md

@@ -1,6 +1,11 @@
 # Grazel
 
-**Grazel** stands for `Gradle` to `Bazel`. It is a Gradle plugin that enables you to migrate Android projects to [Bazel build](https://bazel.build) system in an incremental and automated fashion. 
+**Grazel** stands for `Gradle` to `Bazel`. A Gradle plugin to migrate Android projects to [Bazel build](https://bazel.build) system in an incremental and automated fashion. 
+
+<p align="center">
+<img src="images/grazel-demo.gif" width="100%">
+</p>
+
 
 ## How it works
 
@@ -14,7 +19,6 @@ apply plugin: "kotlin-android"
 
 android {
     compileSdkVersion rootProject.compileSdk
-
     defaultConfig {
         minSdkVersion rootProject.minSdk
         targetSdkVersion rootProject.targetSdk
@@ -54,24 +58,23 @@ kt_android_library(
         "@maven//:androidx_test_espresso_espresso_idling_resource",
     ],
 )
-
 ```
 
 See [migration capabilities](migration_capabilities.md) for supported features. In advanced cases, where entire project might not be [migratable](migration_criteria.md), it migrates part of the graph and sets up [hybrid build](hybrid_builds.md) where part of the graph can be built with Bazel and rest with Gradle.
 
-## Components
-
-* [Gradle plugin](https://github.com/grab/Grazel/tree/master/grazel-gradle-plugin)
-* A Kotlin Starlark DSL to generate Starlark code in a type-safe way.
-* [Grab Bazel Common](https://github.com/grab/grab-bazel-common) - Custom rules to bridge the gap between Gradle/Bazel.
-
 ## Features
 
 * Generate `BUILD.bazel`, `WORKSPACE` for given Android project and reduce the overall migration effort.
-* Setup hybrid build to build part of project graph to build with Bazel and rest with Gradle.
+* Setup [hybrid build](hybrid_builds.md) to build part of project graph to build with Bazel and rest with Gradle.
 * Minimal source changes to codebase - supported by [Grab Bazel Common](https://github.com/grab/grab-bazel-common).
 * Gradle Configuration as source of truth.
 
+## Components
+
+* [Gradle plugin](https://github.com/grab/Grazel/tree/master/grazel-gradle-plugin)
+* A Kotlin Starlark DSL to generate Starlark code in a type-safe way.
+* [Grab Bazel Common](https://github.com/grab/grab-bazel-common) - Custom rules to bridge the gap between Gradle/Bazel.
+
 ## Getting Started
 
 ### Requirements
@@ -92,7 +95,9 @@ See [migration capabilities](migration_capabilities.md) for supported features.
 
 ## Apply Grazel plugin
 
-Grazel is available on Maven Central.
+Grazel is available on Maven Central. 
+
+<img alt="Maven Central" src="https://img.shields.io/maven-central/v/com.grab.grazel/grazel-gradle-plugin?logo=apache-maven&logoColor=%23C71A36&style=flat-square&colorB=00bdd6">
 
 In root `build.gradle`: