Updated the documentation accordingly

Removed an outdated comment about generating documentation, since
`scripts/gen-docs.sh` no longer exists. I also removed
docs/configure_zinc_scala.md`, since the rest of our autogenerated
documentation has been deleted.

CONTRIBUTING.md

@@ -2,14 +2,6 @@
 
 Contributions should follow the [principals](../README.md#principals) of rules_scala_annex.
 
-## Documentation
-
-To generate the [Stardoc](https://github.com/bazelbuild/skydoc),
-
-```
-$ ./scripts/gen-docs.sh
-```
-
 ## Formatting
 
 [Buildifier](https://github.com/bazelbuild/buildtools/blob/master/buildifier) is used to format Skylark files,

README.md

@@ -74,7 +74,7 @@ load("@rules_scala_annex//rules/scala:workspace.bzl", "scala_register_toolchains
 scala_repositories()
 load("@annex//:defs.bzl", annex_pinned_maven_install = "pinned_maven_install")
 annex_pinned_maven_install()
-scala_register_toolchains()
+scala_register_toolchains(default_scala_toolchain_name = "zinc_3")
 
 load("@rules_scala_annex//rules/scalafmt:workspace.bzl", "scalafmt_default_config", "scalafmt_repositories")
 scalafmt_repositories()

docs/newdocs/scala_versions.md

@@ -1,33 +1,40 @@
 ## Specifying the Scala version to use
 
-The scala version used by a buildable target is specified via the `ScalaConfiguration` passed in to the rule's `scala` attribute.
+We use a [toolchain](https://bazel.build/extending/toolchains) to store compiler configuration,
+which includes:
+- Which compiler to use
+- What compile-time and runtime dependencies to add
+- What compiler plugins and options to use
+- Which Zinc compiler bridge to use
+- etc.
 
-This attribute defaults to using the `default_scala` specified via `bind` in the `WORKSPACE` file of the repo. For example, suppose the `ScalaConfiguration` you wish to default to is defined by `//scala:2_13`. In your `WORKSPACE`, you would include:
+We provide two macros for defining Scala toolchains: `register_bootstrap_toolchain` and
+`register_zinc_toolchain`, both of which are in `@rules_scala_annex//rules/register_toolchain.bzl`.
+The latter requires the former.
 
+Once you've registered both types of toolchains, you'll need to tell Bazel about them and set the
+default one (which we recommend is a Zinc toolchain so you can get things like
+unused/undeclared dependency checking and test code coverage checking) via the
+`scala_register_toolchains` repository rule. Something like this should work, assuming this
+repository is mapped to `rules_scala_annex`:
+
+*/BUILD.bazel*
 ```python
-bind(
-    name = "default_scala",
-    actual = "//scala:2_13",
+load(
+    "@rules_scala_annex//rules/register_toolchain.bzl",
+    "register_bootstrap_toolchain",
+    "register_zinc_toolchain",
 )
-```
-
-We provide two means of creating the `ScalaConfiguration`: `configure_bootstrap_scala` and `configure_zinc_scala`. The former is required by the latter.
-
-Example:
 
-```python
 compiler_classpath_2_13 = [
     "@scala_compiler_2_13//jar",
     "@scala_library_2_13//jar",
     "@scala_reflect_2_13//jar",
 ]
 
-runtime_classpath_2_13 = [
-    "@scala_library_2_13//jar",
-]
+runtime_classpath_2_13 = ["@scala_library_2_13//jar"]
 
-# This creates a basic ScalaConfiguration that relies on the scalac compiler
-configure_bootstrap_scala(
+register_bootstrap_toolchain(
     name = "bootstrap_2_13",
     compiler_classpath = compiler_classpath_2_13,
     runtime_classpath = runtime_classpath_2_13,
@@ -38,10 +45,8 @@ configure_bootstrap_scala(
 # compiler bridge needed to configure zinc compiler
 scala_library(
     name = "compiler_bridge_2_13",
-    srcs = [
-        "@compiler_bridge_2_13//:src",
-    ],
-    scala = ":bootstrap_2_13",
+    srcs = ["@compiler_bridge_2_13//:src"],
+    scala_toolchain_name = "bootstrap_2_13",
     visibility = ["//visibility:public"],
     deps = compiler_classpath_2_13 + [
         "@scala_annex_org_scala_sbt_compiler_interface//jar",
@@ -50,7 +55,7 @@ scala_library(
 )
 
 # This augments the configuration to configure the zinc compiler
-configure_zinc_scala(
+register_zinc_toolchain(
     name = "zinc_2_13",
     compiler_bridge = ":compiler_bridge_2_13",
     compiler_classpath = compiler_classpath_2_13,
@@ -60,24 +65,41 @@ configure_zinc_scala(
 )
 ```
 
-It is possible to use a different `ScalaConfiguration` on different build targets. All you need to do is specify a different one in the `scala` attribute. If no `scala` attribute is specified, the `default_scala` bound to in your `WORKSPACE` is used.
+*/WORKSPACE*
+```python
+load("@rules_scala_annex//rules/scala:workspace.bzl", "scala_register_toolchains")
+
+...
+
+scala_register_toolchains(
+    toolchains = ["//:bootstrap_2_13", "//:zinc_2_13"],
+    default_scala_toolchain_name = "zinc_2_13",
+)
+
+...
+```
+
+Take note of the `scala_toolchain_name` attribute on `scala_library` and the other Scala rules. Each
+toolchain that's registered via `scala_register_toolchains` is identified by its `name`. Individual
+Scala targets can be made to use a particular toolchain by setting their `scala_toolchain_name`
+attribute.
 
 For example:
 
 ```python
 scala_library(
   name = "example_compiled_with_scalac",
   srcs = glob(["**/*.scala"])
-  scala = "<package>:bootstrap_2_13
+  scala_toolchain_name = "bootstrap_2_13",
 )
 
 scala_library(
   name = "example_compiled_with_zinc",
   srcs = glob(["**/*.scala"])
-  scala = "<package>:zinc_2_13
+  scala_toolchain_name = "zinc_2_13",
 )
 
-# This would use whatever //external:default_scala points to (i.e. what you bind default_scala to in your WORKSPACE)
+# This would use the default toolchain, which we configured via `scala_register_toolchains` above
 scala_library(
   name = "example_compiled_with_default_scala",
   srcs = glob(["**/*.scala"])

docs/scala.md

@@ -42,7 +42,7 @@ Each define may have a value of:
 
 Failed checks emit suggested [buildozer](https://github.com/bazelbuild/buildtools/tree/master/buildozer) commands.
 
-You may also toggle deps check via [configure_zinc_scala](configure_zinc_scala.md):
+You may also toggle deps check via `register_zinc_toolchain`:
 
 * `deps_direct` - Work the same as `scala_deps_direct`.
 * `deps_used` - Work the same as `scala_deps_used`.