Update docs (bazel-contrib#329)

* escape rule names

* strict deps documentation

Author: ittaiz

README.md

@@ -395,7 +395,7 @@ of a series of independent files in a larger target into smaller ones. This lets
 and also build the indvidual targets in parallel. Downstream targets should not be aware of its presence.
 
 <a name="scala_test_suite"></a>
-## scala_test_suite
+## scala\_test_suite
 
 The scala test suite allows you to define a glob or series of targets to generate sub
 scala tests for. The outer target defines a native test suite to run all the inner tests. This allows splitting up
@@ -469,7 +469,7 @@ thrift_library(name, srcs, deps, absolute_prefix, absolute_prefixes)
 </table>
 
 <a name="scalapb_proto_library"></a>
-## scalapb_proto_library
+## scalapb\_proto_library
 
 You first need to add the following to your WORKSPACE file:
 
@@ -543,6 +543,30 @@ generated by the [ScalaPB compiler](https://github.com/scalapb/ScalaPB).
   </tbody>
 </table>
 
+## [Experimental] Using strict-deps
+Bazel pushes towards explicit and minimial dependencies to keep BUILD file higene and allow for targets to refactor their dependencies without fear of downstream breaking.    
+Currently rules_scala does this at the cost of having cryptic `scalac` errors when one mistakenly depends on a transitive dependency or, as more often the case for some, a transitive dependency is needed to [please scalac](https://github.com/scalacenter/advisoryboard/blob/master/proposals/009-improve-direct-dependency-experience.md) itself.   
+To learn more about the motivation of strict-deps itself you can visit this Bazel blog [post](https://blog.bazel.build/2017/06/28/sjd-unused_deps.html) on the subject.
+
+To use it just add `--strict_java_deps=WARN|ERROR` to your `bazel` invocation.
+In both cases of `WARN` or `ERROR` you will get the following text in the event of a violation:
+```
+...
+Target '//some_package:transitive_dependency' is used but isn't explicitly declared, please add it to the deps.
+You can use the following buildozer command:
+buildozer 'add deps //some_package:transitive_dependency' //some_other_package:transitive_dependency_user
+```
+Note that if you have `buildozer` installed you can just run the last line and have it automatically apply the fix for you.    
+
+**Caveats:**
+<ul>
+    <li>Extra builds- when strict-deps is on the transitive dependencies are inputs to the compilation action which means you can potentially have more build triggers for changes the cross the ijar boundary </li>
+    <li>Label propagation- since label of targets are needed for the clear message and since it's not currently supported by JavaInfo from bazel we manually propagate it. This means that the error messages have a significantly lower grade if you don't use one of the scala rules or scala_import (since they don't propagate these labels)</li>
+    <li>javac outputs incorrect targets due to a problem we're tracing down. Practically we've noticed it's pretty trivial to understand the correct target (i.e. it's almost a formatting problem) </li>
+  </ul>
+  
+Note: Currently strict-deps is protected by a feature toggle but we're strongly considering making it the default behavior as `java_*` rules do.
+
 ## Building from source
 Test & Build:
 ```