Updated crate_universe setup guide (#1202)

* Updated crate_universe setup guide

* Regenerate documentation

crate_universe/3rdparty/BUILD.bazel

@@ -16,5 +16,8 @@ filegroup(
 
 filegroup(
     name = "bzl_srcs",
-    srcs = glob(["*.bzl"]),
+    srcs = glob(["*.bzl"]) + [
+        "//crate_universe/3rdparty/crates:crates.bzl",
+        "//crate_universe/3rdparty/crates:defs.bzl",
+    ],
 )

crate_universe/BUILD.bazel

@@ -34,6 +34,7 @@ filegroup(
     srcs = glob(["*.bzl"]) + [
         "//crate_universe/3rdparty:bzl_srcs",
         "//crate_universe/private:bzl_srcs",
+        "//crate_universe/tools:bzl_srcs",
     ],
     visibility = ["//visibility:public"],
 )

crate_universe/README.md

@@ -1,6 +1,6 @@
-# Cargo->Bazel
+# Crate Universe
 
-`cargo->bazel` is a tool used which uses [Cargo][cargo] to generate build targets for [Bazel][bazel].
+`crate_universe` is a collection of tools which use [Cargo][cargo] to generate build targets for [Bazel][bazel].
 
 ## [Documentation][docs]
 

crate_universe/crates.bzl

@@ -1,10 +1,12 @@
 """A module defining dependencies of the `cargo-bazel` Rust target"""
 
 load("@rules_rust//rust:defs.bzl", "rust_common")
-load("//crate_universe:defs.bzl", "crate", "crates_repository", "crates_vendor")
 load("//crate_universe:deps_bootstrap.bzl", "cargo_bazel_bootstrap")
 load("//crate_universe/3rdparty:third_party_deps.bzl", "third_party_deps")
 load("//crate_universe/3rdparty/crates:crates.bzl", _vendor_crate_repositories = "crate_repositories")
+load("//crate_universe/private:crate.bzl", "crate")
+load("//crate_universe/private:crates_repository.bzl", "crates_repository")
+load("//crate_universe/private:crates_vendor.bzl", "crates_vendor")
 load("//crate_universe/private:vendor_utils.bzl", "crates_vendor_deps")
 load("//crate_universe/tools/cross_installer:cross_installer_deps.bzl", "cross_installer_deps")
 

crate_universe/defs.bzl

@@ -6,13 +6,28 @@ Crate Universe is a set of Bazel rule for generating Rust targets using Cargo.
 
 `crate_universe` is experimental, and may have breaking API changes at any time. These instructions may also change without notice.
 
+## Setup
+
+After loading `rules_rust` in your workspace, set the following to begin using `crate_universe`:
+
+```python
+load("@rules_rust//crate_universe:crates.bzl", "crate_deps_repository")
+
+crate_deps_repository()
+```
+
+Note that if the current version of `rules_rust` is not a release artifact, you may need to set additional
+flags such as [`bootstrap = True`](#crate_deps_repository-bootstrap) on the `crate_deps_repository`
+call above or [crates_repository::generator_urls](#crates_repository-generator_urls) in uses of `crates_repository`.
+
 ## Rules
 
+- [crate_deps_repository](#crate_deps_repository)
 - [crates_repository](#crates_repository)
 - [crates_vendor](#crates_vendor)
+- [crate.annotation](#crateannotation)
 - [crate.spec](#cratespec)
 - [crate.workspace_member](#crateworkspace_member)
-- [crate.annotation](#crateannotation)
 - [render_config](#render_config)
 - [splicing_config](#splicing_config)
 
@@ -142,8 +157,13 @@ rust_test(
 [cc]: https://docs.bazel.build/versions/main/be/c-cpp.html
 [proto]: https://rules-proto-grpc.com/en/latest/lang/rust.html
 [ra]: https://rust-analyzer.github.io/
+
 """
 
+load(
+    "//crate_universe:crates.bzl",
+    _crate_deps_repository = "crate_deps_repository",
+)
 load(
     "//crate_universe/private:crate.bzl",
     _crate = "crate",
@@ -166,6 +186,7 @@ load(
 )
 
 crate = _crate
+crate_deps_repository = _crate_deps_repository
 crates_repository = _crates_repository
 crates_vendor = _crates_vendor
 render_config = _render_config

crate_universe/tools/BUILD.bazel

@@ -6,3 +6,11 @@ filegroup(
     ],
     visibility = ["//crate_universe:__subpackages__"],
 )
+
+filegroup(
+    name = "bzl_srcs",
+    srcs = [
+        "//crate_universe/tools/cross_installer:bzl_srcs",
+    ],
+    visibility = ["//crate_universe:__subpackages__"],
+)

crate_universe/tools/cross_installer/BUILD.bazel

@@ -35,3 +35,9 @@ filegroup(
     ],
     visibility = ["//crate_universe/tools:__pkg__"],
 )
+
+filegroup(
+    name = "bzl_srcs",
+    srcs = glob(["**/*.bzl"]),
+    visibility = ["//crate_universe/tools:__pkg__"],
+)

docs/BUILD.bazel

@@ -13,6 +13,7 @@ bzl_library(
     ],
     deps = [
         "@bazel_skylib//lib:paths",
+        "@bazel_skylib//lib:selects",
         "@bazel_skylib//rules:common_settings",
         "@rules_proto//proto:defs",
         "@rules_proto//proto:repositories",

docs/crate_universe.md

@@ -8,13 +8,28 @@ Crate Universe is a set of Bazel rule for generating Rust targets using Cargo.
 
 `crate_universe` is experimental, and may have breaking API changes at any time. These instructions may also change without notice.
 
+## Setup
+
+After loading `rules_rust` in your workspace, set the following to begin using `crate_universe`:
+
+```python
+load("@rules_rust//crate_universe:crates.bzl", "crate_deps_repository")
+
+crate_deps_repository()
+```
+
+Note that if the current version of `rules_rust` is not a release artifact, you may need to set additional
+flags such as [`bootstrap = True`](#crate_deps_repository-bootstrap) on the `crate_deps_repository`
+call above or [crates_repository::generator_urls](#crates_repository-generator_urls) in uses of `crates_repository`.
+
 ## Rules
 
+- [crate_deps_repository](#crate_deps_repository)
 - [crates_repository](#crates_repository)
 - [crates_vendor](#crates_vendor)
+- [crate.annotation](#crateannotation)
 - [crate.spec](#cratespec)
 - [crate.workspace_member](#crateworkspace_member)
-- [crate.annotation](#crateannotation)
 - [render_config](#render_config)
 - [splicing_config](#splicing_config)
 
@@ -146,6 +161,7 @@ rust_test(
 [ra]: https://rust-analyzer.github.io/
 
 
+
 <a id="#crates_repository"></a>
 
 ## crates_repository
@@ -336,6 +352,25 @@ Define information for extra workspace members
 string: A json encoded string of all inputs
 
 
+<a id="#crate_deps_repository"></a>
+
+## crate_deps_repository
+
+<pre>
+crate_deps_repository(<a href="#crate_deps_repository-rust_version">rust_version</a>, <a href="#crate_deps_repository-bootstrap">bootstrap</a>)
+</pre>
+
+Define dependencies of the `cargo-bazel` Rust target
+
+**PARAMETERS**
+
+
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="crate_deps_repository-rust_version"></a>rust_version |  The version of rust to use when generating dependencies.   |  <code>"1.59.0"</code> |
+| <a id="crate_deps_repository-bootstrap"></a>bootstrap |  If true, a <code>cargo_bootstrap_repository</code> target will be generated.   |  <code>False</code> |
+
+
 <a id="#render_config"></a>
 
 ## render_config