[doc] Added a note on the Pegdown Doclet plugin problem

[ci skip]

Author: Clément Le Provost

doc/build.md

@@ -9,7 +9,7 @@ The client exists in two different flavors:
 
 - The **online** flavor, which is the regular API client. Its source code is located under the `algoliasearch/src/main` directory. It gets published to Maven Central as `algoliasearch-android`.
 
-- The **offline** flavor, which is a superset of the online flavor. In addition to the main source code, it adds the `algoliasearch/src/offline` directory. It gets published to Maven Central as `algoliasearch-offline-android`. This flavor has a dependency on the Algolia Search Offline Core module (`algoliasearch-offline-core-android` in Maven). 
+- The **offline** flavor, which is a superset of the online flavor. In addition to the main source code, it adds the `algoliasearch/src/offline` directory. It gets published to Maven Central as `algoliasearch-offline-android`. This flavor has a dependency on the Algolia Search Offline Core module (`algoliasearch-offline-core-android` in Maven).
 
 
 ## Problem
@@ -35,3 +35,23 @@ Consequently, the approach taken is as follows:
 
 - Then use Gradle as you would with a normal module.
 
+
+# Build-time dependencies
+
+We rely on the [Pegdown Doclet](https://github.com/Abnaxos/pegdown-doclet) to generate our reference documentation ("Javadoc"). This is a built-time dependency that does not impact pre-built binaries.
+
+However, when targeting the source version of the API Client (e.g. when developing or debugging), this dependency bubbles up to the dependent project. After literally hours of searching the Internet, I found no way to persuade Gradle to automatically draw this dependency. All normal tricks (like using `compileOnly`, `provided` or `classpath`) failed miserably. Therefore, you have to put this in the *top-level* `build.gradle` from the dependent project:
+
+```
+buildscript {
+    // [...]
+    dependencies {
+        // [...]
+        classpath 'ch.raffael.pegdown-doclet:pegdown-doclet:1.3' // FIXME: DO NOT COMMIT
+    }
+}
+```
+
+An alternative is just to comment out the line referring to the plugin in the API Client's `common.gradle`.
+
+**Warning:** In either case, please make sure not to commit those changes!