Update target scope docs (#4553)

Add user documentation about the `test` scope, and how to emulate the Maven
`provided` scope in Pants.

examples/src/java/org/pantsbuild/example/BUILD

@@ -19,6 +19,7 @@ page(
   source='from_maven.md',
   links=[
     ':3rdparty_jvm',
+    ':readme',
   ],
 )
 

examples/src/java/org/pantsbuild/example/README.md

@@ -513,7 +513,7 @@ Target Scopes
 
 ### Overview
 
-Pants supports marking targets with a `scope` value which the JVM backend will use to filter
+Pants supports marking targets with one or more `scope` values which the JVM backend will use to filter
 dependency subgraphs at compiletime and runtime. Scopes are also used for unused dependency
 detection: only `default` scoped targets are eligible to be considered as "unused" deps.
 
@@ -538,6 +538,9 @@ Pants' built in scopes are:
 * `runtime`: Indicates that a target is only used at runtime, and should not be presented to the
   compiler. Targets which are only used via JVM reflection are good examples of runtime-only
   dependencies.
+* `test`: Indicates that a target is used when running tests. This scope is typically used in
+  addition to another scope (e.g.: `scope='compile test'`). Targets which are are provided by an
+  external execution environment are good examples of compile+test dependencies.
 * `forced` _(available from pants 1.1.0)_: The `forced` scope is equivalent to the `default` scope, but additionally indicates
   that a target is not eligible to be considered an "unused" dependency. It is sometimes necessary
   to mark a target `forced` due to false positives in the static analysis used for unused
@@ -555,6 +558,15 @@ that target:
       scope='runtime',
     )
 
+Multiple scopes can be specified. The equivalent of Maven's `provided` scope can be expressed by
+specifying both compile and test scopes.
+
+    :::python
+    java_library(name='lib',
+      ..,
+      scope='compile test',
+    )
+
 If the scope of a target is not matched for a particular context, the entire subgraph represented
 by the dependency will be pruned. This means that if a dependency 'B' of a target 'A' is marked
 `compile` (for example), the dependency targets of 'B' will only be included at compiletime (unless

examples/src/java/org/pantsbuild/example/from_maven.md

@@ -107,4 +107,30 @@ jvm_binary(name='your-bin',
               # We need to add this as it is overridden by adding the reference.conf one above.
               Duplicate('^META-INF/services/', Duplicate.CONCAT_TEXT)
           ]))
-```
+```
+
+**Dependency Scopes**<br>
+
+Pants supports dependency scopes. To emulate Maven's `provided` scope you
+can specify both the `compile` and `test` scopes for a target. For details,
+see [[JVM Projects with Pants|pants('examples/src/java/org/pantsbuild/example:readme')]].
+
+Maven
+```xml
+<dependency>
+  <groupId>org.apache.spark</groupId>
+  <artifactId>spark-core_2.11</artifactId>
+  <scope>provided</scope>
+</dependency>
+```
+
+Pants
+```python
+jar_library(
+  name='spark-core',
+  jars=[
+    scala_jar(org='org.apache.spark', name='spark-core', rev='2.1.0'),
+  ],
+  scope='compile test',
+)
+```