Updated rust_bindgen dependencies API (bazelbuild#1354)

* Moved `rust_bindgen` docs into generated stardoc

* Regenerate documentation

WORKSPACE.bazel

@@ -18,9 +18,11 @@ load("@rules_rust//proto:transitive_repositories.bzl", "rust_proto_transitive_re
 
 rust_proto_transitive_repositories()
 
-load("@rules_rust//bindgen:repositories.bzl", "rust_bindgen_repositories")
+load("@rules_rust//bindgen:repositories.bzl", "rust_bindgen_dependencies", "rust_bindgen_register_toolchains")
 
-rust_bindgen_repositories()
+rust_bindgen_dependencies()
+
+rust_bindgen_register_toolchains()
 
 load("@rules_rust//tools/rust_analyzer:deps.bzl", "rust_analyzer_deps")
 

bindgen/README.md

@@ -1,82 +1,8 @@
 # Rust Bindgen Rules
 
-<div class="toc">
-  <h2>Rules</h2>
-  <ul>
-    <li><a href="docs/index.md#rust_bindgen_toolchain">rust_bindgen_toolchain</a></li>
-    <li>rust_bindgen</li>
-    <li>rust_bindgen_library</li>
-  </ul>
-</div>
-
-## Overview
-
 These rules are for using [Bindgen][bindgen] to generate [Rust][rust] bindings to C (and some C++) libraries.
 
+See the `rules_rust` documentation for more info: https://bazelbuild.github.io/rules_rust/rust_bindgen.html
+
 [rust]: http://www.rust-lang.org/
 [bindgen]: https://github.com/rust-lang/rust-bindgen
-
-See the [bindgen example](../examples/ffi/rust_calling_c/simple/BUILD.bazel#L9) for a more complete example of use.
-
-### Setup
-
-To use the Rust bindgen rules, add the following to your `WORKSPACE` file to add the
-external repositories for the Rust bindgen toolchain (in addition to the [rust rules setup](..)):
-
-```python
-load("@rules_rust//bindgen:repositories.bzl", "rust_bindgen_repositories")
-
-rust_bindgen_repositories()
-```
-This makes the default toolchain defined in [`@rules_rust`](./BUILD) available.
-
-[raze]: https://github.com/google/cargo-raze
-
-It will load crate dependencies of bindgen that are generated using
-[cargo raze][raze] inside the rules_rust
-repository. However, using those dependencies might conflict with other uses
-of [cargo raze][raze]. If you need to change
-those dependencies, please see the [dedicated section below](#custom-deps).
-
-For additional information, see the [Bazel toolchains documentation](https://docs.bazel.build/versions/master/toolchains.html).
-
-## <a name="custom-deps">Customizing dependencies
-
-These rules depends on the [`bindgen`](https://crates.io/crates/bindgen) binary crate, and it 
-in turn depends on both a clang binary and the clang library. To obtain these dependencies,
-`rust_bindgen_repositories` imports bindgen and its dependencies using BUILD files generated with
-[`cargo raze`][raze], along with a tarball of clang.
-
-If you want to change the bindgen used, or use [`cargo raze`][raze] in a more
-complex scenario (with more dependencies), you must redefine those
-dependencies.
-
-To do this, once you've imported the needed dependencies (see our
-[Cargo.toml](./raze/Cargo.toml) file to see the default dependencies), you
-need to create your own toolchain. To do so you can create a BUILD
-file with your [`rust_bindgen_toolchain`](../docs/index.md#rust_bindgen_toolchain) definition, for example:
-
-```python
-load("@rules_rust//bindgen:bindgen.bzl", "rust_bindgen_toolchain")
-
-rust_bindgen_toolchain(
-    name = "bindgen-toolchain-impl",
-    bindgen = "//my/raze:cargo_bin_bindgen",
-    clang = "//my/clang:clang",
-    libclang = "//my/clang:libclang.so",
-    libstdcxx = "//my/cpp:libstdc++",
-)
-
-toolchain(
-    name = "bindgen-toolchain",
-    toolchain = "bindgen-toolchain-impl",
-    toolchain_type = "@rules_rust//bindgen:bindgen_toolchain",
-)
-```
-
-Now that you have your own toolchain, you need to register it by
-inserting the following statement in your `WORKSPACE` file:
-
-```python
-register_toolchains("//my/toolchains:bindgen-toolchain")
-```

bindgen/bindgen.bzl

@@ -187,14 +187,14 @@ rust_bindgen = rule(
             doc = "Flags to pass directly to the bindgen executable. See https://rust-lang.github.io/rust-bindgen/ for details.",
         ),
         "cc_lib": attr.label(
-            doc = "The cc_library that contains the .h file. This is used to find the transitive includes.",
+            doc = "The cc_library that contains the `.h` file. This is used to find the transitive includes.",
             providers = [CcInfo],
         ),
         "clang_flags": attr.string_list(
             doc = "Flags to pass directly to the clang executable.",
         ),
         "header": attr.label(
-            doc = "The .h file to generate bindings for.",
+            doc = "The `.h` file to generate bindings for.",
             allow_single_file = True,
         ),
         "rustfmt": attr.bool(
@@ -232,7 +232,34 @@ def _rust_bindgen_toolchain_impl(ctx):
 
 rust_bindgen_toolchain = rule(
     _rust_bindgen_toolchain_impl,
-    doc = "The tools required for the `rust_bindgen` rule.",
+    doc = """\
+The tools required for the `rust_bindgen` rule.
+
+This rule depends on the [`bindgen`](https://crates.io/crates/bindgen) binary crate, and it 
+in turn depends on both a clang binary and the clang library. To obtain these dependencies,
+`rust_bindgen_dependencies` imports bindgen and its dependencies.
+
+```python
+load("@rules_rust//bindgen:bindgen.bzl", "rust_bindgen_toolchain")
+
+rust_bindgen_toolchain(
+    name = "bindgen_toolchain_impl",
+    bindgen = "//my/rust:bindgen",
+    clang = "//my/clang:clang",
+    libclang = "//my/clang:libclang.so",
+    libstdcxx = "//my/cpp:libstdc++",
+)
+
+toolchain(
+    name = "bindgen_toolchain",
+    toolchain = "bindgen_toolchain_impl",
+    toolchain_type = "@rules_rust//bindgen:bindgen_toolchain",
+)
+```
+
+This toolchain will then need to be registered in the current `WORKSPACE`.
+For additional information, see the [Bazel toolchains documentation](https://docs.bazel.build/versions/master/toolchains.html).
+""",
     attrs = {
         "bindgen": attr.label(
             doc = "The label of a `bindgen` executable.",

bindgen/repositories.bzl

@@ -18,15 +18,32 @@ load("@bazel_tools//tools/build_defs/repo:utils.bzl", "maybe")
 load("//bindgen/raze:crates.bzl", "rules_rust_bindgen_fetch_remote_crates")
 
 # buildifier: disable=unnamed-macro
-def rust_bindgen_repositories():
+def rust_bindgen_dependencies():
     """Declare dependencies needed for bindgen."""
 
     # nb. The bindgen rule itself should work on any platform.
     _bindgen_clang_repositories()
 
     rules_rust_bindgen_fetch_remote_crates()
 
-    native.register_toolchains(str(Label("//bindgen:default_bindgen_toolchain")))
+# buildifier: disable=unnamed-macro
+def rust_bindgen_register_toolchains(register_toolchains = True):
+    """Registers the default toolchains for the `rules_rust` [bindgen][bg] rules.
+
+    [bg]: https://rust-lang.github.io/rust-bindgen/
+
+    Args:
+        register_toolchains (bool, optional): Whether or not to register toolchains.
+    """
+    if register_toolchains:
+        native.register_toolchains(str(Label("//bindgen:default_bindgen_toolchain")))
+
+# buildifier: disable=unnamed-macro
+def rust_bindgen_repositories():
+    """**Deprecated**: Instead use [rust_bindgen_dependencies](#rust_bindgen_dependencies) and [rust_bindgen_register_toolchains](#rust_bindgen_register_toolchains)"""
+
+    rust_bindgen_dependencies()
+    rust_bindgen_register_toolchains()
 
 _COMMON_WORKSPACE = """\
 workspace(name = "{}")

docs/BUILD.bazel

@@ -76,9 +76,11 @@ PAGES = dict([
     ),
     page(
         name = "rust_bindgen",
+        header_template = ":rust_bindgen.vm",
         symbols = [
             "rust_bindgen_library",
-            "rust_bindgen_repositories",
+            "rust_bindgen_dependencies",
+            "rust_bindgen_register_toolchains",
             "rust_bindgen_toolchain",
             "rust_bindgen",
         ],

docs/flatten.md

@@ -16,8 +16,9 @@
 * [rust_analyzer_aspect](#rust_analyzer_aspect)
 * [rust_binary](#rust_binary)
 * [rust_bindgen](#rust_bindgen)
+* [rust_bindgen_dependencies](#rust_bindgen_dependencies)
 * [rust_bindgen_library](#rust_bindgen_library)
-* [rust_bindgen_repositories](#rust_bindgen_repositories)
+* [rust_bindgen_register_toolchains](#rust_bindgen_register_toolchains)
 * [rust_bindgen_toolchain](#rust_bindgen_toolchain)
 * [rust_clippy](#rust_clippy)
 * [rust_clippy_aspect](#rust_clippy_aspect)
@@ -317,9 +318,9 @@ Generates a rust source file from a cc_library and a header.
 | :------------- | :------------- | :------------- | :------------- | :------------- |
 | <a id="rust_bindgen-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required |  |
 | <a id="rust_bindgen-bindgen_flags"></a>bindgen_flags |  Flags to pass directly to the bindgen executable. See https://rust-lang.github.io/rust-bindgen/ for details.   | List of strings | optional | [] |
-| <a id="rust_bindgen-cc_lib"></a>cc_lib |  The cc_library that contains the .h file. This is used to find the transitive includes.   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
+| <a id="rust_bindgen-cc_lib"></a>cc_lib |  The cc_library that contains the <code>.h</code> file. This is used to find the transitive includes.   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
 | <a id="rust_bindgen-clang_flags"></a>clang_flags |  Flags to pass directly to the clang executable.   | List of strings | optional | [] |
-| <a id="rust_bindgen-header"></a>header |  The .h file to generate bindings for.   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
+| <a id="rust_bindgen-header"></a>header |  The <code>.h</code> file to generate bindings for.   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
 | <a id="rust_bindgen-rustfmt"></a>rustfmt |  Enable or disable running rustfmt on the generated file.   | Boolean | optional | True |
 
 
@@ -333,6 +334,32 @@ rust_bindgen_toolchain(<a href="#rust_bindgen_toolchain-name">name</a>, <a href=
 
 The tools required for the `rust_bindgen` rule.
 
+This rule depends on the [`bindgen`](https://crates.io/crates/bindgen) binary crate, and it 
+in turn depends on both a clang binary and the clang library. To obtain these dependencies,
+`rust_bindgen_dependencies` imports bindgen and its dependencies.
+
+```python
+load("@rules_rust//bindgen:bindgen.bzl", "rust_bindgen_toolchain")
+
+rust_bindgen_toolchain(
+    name = "bindgen_toolchain_impl",
+    bindgen = "//my/rust:bindgen",
+    clang = "//my/clang:clang",
+    libclang = "//my/clang:libclang.so",
+    libstdcxx = "//my/cpp:libstdc++",
+)
+
+toolchain(
+    name = "bindgen_toolchain",
+    toolchain = "bindgen_toolchain_impl",
+    toolchain_type = "@rules_rust//bindgen:bindgen_toolchain",
+)
+```
+
+This toolchain will then need to be registered in the current `WORKSPACE`.
+For additional information, see the [Bazel toolchains documentation](https://docs.bazel.build/versions/master/toolchains.html).
+
+
 **ATTRIBUTES**
 
 
@@ -1540,18 +1567,6 @@ Arguments are the same as `rust_bindgen`, and `kwargs` are passed directly to ru
 | <a id="rust_bindgen_library-kwargs"></a>kwargs |  Arguments to forward to the underlying <code>rust_library</code> rule.   |  none |
 
 
-<a id="#rust_bindgen_repositories"></a>
-
-## rust_bindgen_repositories
-
-<pre>
-rust_bindgen_repositories()
-</pre>
-
-Declare dependencies needed for bindgen.
-
-
-
 <a id="#rust_proto_repositories"></a>
 
 ## rust_proto_repositories

docs/rust_bindgen.md

@@ -2,10 +2,40 @@
 # Rust Bindgen
 
 * [rust_bindgen_library](#rust_bindgen_library)
-* [rust_bindgen_repositories](#rust_bindgen_repositories)
+* [rust_bindgen_dependencies](#rust_bindgen_dependencies)
+* [rust_bindgen_register_toolchains](#rust_bindgen_register_toolchains)
 * [rust_bindgen_toolchain](#rust_bindgen_toolchain)
 * [rust_bindgen](#rust_bindgen)
 
+
+## Overview
+
+These rules are for using [Bindgen][bindgen] to generate [Rust][rust] bindings to C (and some C++) libraries.
+
+[rust]: http://www.rust-lang.org/
+[bindgen]: https://github.com/rust-lang/rust-bindgen
+
+See the [bindgen example](https://github.com/bazelbuild/rules_rust/tree/main/examples/ffi/rust_calling_c/simple/BUILD.bazel#L9) for a more complete example of use.
+
+### Setup
+
+To use the Rust bindgen rules, add the following to your `WORKSPACE` file to add the
+external repositories for the Rust bindgen toolchain (in addition to the [rust rules setup](https://bazelbuild.github.io/rules_rust/#setup)):
+
+```python
+load("@rules_rust//bindgen:repositories.bzl", "rust_bindgen_dependencies", "rust_bindgen_register_toolchains")
+
+rust_bindgen_dependencies()
+
+rust_bindgen_register_toolchains()
+```
+
+---
+
+---
+
+
+
 <a id="#rust_bindgen"></a>
 
 ## rust_bindgen
@@ -23,9 +53,9 @@ Generates a rust source file from a cc_library and a header.
 | :------------- | :------------- | :------------- | :------------- | :------------- |
 | <a id="rust_bindgen-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required |  |
 | <a id="rust_bindgen-bindgen_flags"></a>bindgen_flags |  Flags to pass directly to the bindgen executable. See https://rust-lang.github.io/rust-bindgen/ for details.   | List of strings | optional | [] |
-| <a id="rust_bindgen-cc_lib"></a>cc_lib |  The cc_library that contains the .h file. This is used to find the transitive includes.   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
+| <a id="rust_bindgen-cc_lib"></a>cc_lib |  The cc_library that contains the <code>.h</code> file. This is used to find the transitive includes.   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
 | <a id="rust_bindgen-clang_flags"></a>clang_flags |  Flags to pass directly to the clang executable.   | List of strings | optional | [] |
-| <a id="rust_bindgen-header"></a>header |  The .h file to generate bindings for.   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
+| <a id="rust_bindgen-header"></a>header |  The <code>.h</code> file to generate bindings for.   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
 | <a id="rust_bindgen-rustfmt"></a>rustfmt |  Enable or disable running rustfmt on the generated file.   | Boolean | optional | True |
 
 
@@ -39,6 +69,32 @@ rust_bindgen_toolchain(<a href="#rust_bindgen_toolchain-name">name</a>, <a href=
 
 The tools required for the `rust_bindgen` rule.
 
+This rule depends on the [`bindgen`](https://crates.io/crates/bindgen) binary crate, and it 
+in turn depends on both a clang binary and the clang library. To obtain these dependencies,
+`rust_bindgen_dependencies` imports bindgen and its dependencies.
+
+```python
+load("@rules_rust//bindgen:bindgen.bzl", "rust_bindgen_toolchain")
+
+rust_bindgen_toolchain(
+    name = "bindgen_toolchain_impl",
+    bindgen = "//my/rust:bindgen",
+    clang = "//my/clang:clang",
+    libclang = "//my/clang:libclang.so",
+    libstdcxx = "//my/cpp:libstdc++",
+)
+
+toolchain(
+    name = "bindgen_toolchain",
+    toolchain = "bindgen_toolchain_impl",
+    toolchain_type = "@rules_rust//bindgen:bindgen_toolchain",
+)
+```
+
+This toolchain will then need to be registered in the current `WORKSPACE`.
+For additional information, see the [Bazel toolchains documentation](https://docs.bazel.build/versions/master/toolchains.html).
+
+
 **ATTRIBUTES**
 
 
@@ -79,15 +135,3 @@ Arguments are the same as `rust_bindgen`, and `kwargs` are passed directly to ru
 | <a id="rust_bindgen_library-kwargs"></a>kwargs |  Arguments to forward to the underlying <code>rust_library</code> rule.   |  none |
 
 
-<a id="#rust_bindgen_repositories"></a>
-
-## rust_bindgen_repositories
-
-<pre>
-rust_bindgen_repositories()
-</pre>
-
-Declare dependencies needed for bindgen.
-
-
-