crate_universe docs: Split bzlmod from workspace (#2700)

Previously the bzlmod symbols were not documented at all, and in places
they are different from the WORKSPACE versions.

This at least hosts both.

Fixes #2696

.github/release_notes.template

@@ -1,5 +1,13 @@
 # {version}
 
+## Bzlmod
+
+```python
+bazel_dep(name = "rules_rust", version = "{version}")
+```
+
+## WORKSPACE
+
 ```python
 load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
 http_archive(

crate_universe/BUILD.bazel

@@ -12,7 +12,8 @@ exports_files(
         "Cargo.toml",
         "Cargo.lock",
         "defs.bzl",
-        "docs.bzl",
+        "docs_bzlmod.bzl",
+        "docs_workspace.bzl",
     ],
     visibility = ["//visibility:public"],
 )

crate_universe/docs_bzlmod.bzl

@@ -0,0 +1,21 @@
+"""# Crate Universe
+
+Crate Universe is a set of Bazel rule for generating Rust targets using Cargo.
+
+This doc describes using crate_universe with bzlmod.
+
+If you're using a WORKSPACE file, please see [the WORKSPACE equivalent of this doc](crate_universe.html).
+
+There are some examples of using crate_universe with bzlmod:
+
+* https://github.com/bazelbuild/rules_rust/blob/main/examples/bzlmod/hello_world/MODULE.bazel
+* https://github.com/bazelbuild/rules_rust/blob/main/examples/bzlmod/override_target/MODULE.bazel
+* https://github.com/bazelbuild/rules_rust/blob/main/examples/bzlmod/all_crate_deps/MODULE.bazel
+"""
+
+load(
+    "//crate_universe:extension.bzl",
+    _crate = "crate",
+)
+
+crate = _crate

crate_universe/docs.bzl → crate_universe/docs_workspace.bzl

@@ -2,6 +2,10 @@
 
 Crate Universe is a set of Bazel rule for generating Rust targets using Cargo.
 
+This doc describes using crate_universe from a WORKSPACE file.
+
+If you're using bzlmod, please see [the bzlmod equivalent of this doc](crate_universe_bzlmod.html).
+
 ## Setup
 
 After loading `rules_rust` in your workspace, set the following to begin using `crate_universe`:

crate_universe/private/module_extensions/BUILD.bazel

@@ -0,0 +1,13 @@
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+
+filegroup(
+    name = "bzl_srcs",
+    srcs = glob(["*.bzl"]),
+    visibility = ["//visibility:public"],
+)
+
+bzl_library(
+    name = "bzl_lib",
+    srcs = [":bzl_srcs"],
+    visibility = ["//visibility:public"],
+)

docs/BUILD.bazel

@@ -1,5 +1,5 @@
 load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
-load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
+load("@stardoc//stardoc:stardoc.bzl", "stardoc")
 load("//:page.bzl", "gen_header", "page")
 
 package(default_visibility = ["//visibility:private"])
@@ -11,8 +11,10 @@ bzl_library(
         "@com_google_protobuf//:bzl_srcs",
     ],
     deps = [
+        "@bazel_features//:features",
         "@bazel_skylib//lib:paths",
         "@bazel_skylib//lib:selects",
+        "@bazel_skylib//lib:structs",
         "@bazel_skylib//rules:common_settings",
         "@rules_proto//proto:defs",
         "@rules_proto//proto:repositories",
@@ -27,6 +29,7 @@ bzl_library(
         "@rules_rust//bindgen:bzl_lib",
         "@rules_rust//cargo:bzl_lib",
         "@rules_rust//crate_universe:bzl_lib",
+        "@rules_rust//crate_universe/private/module_extensions:bzl_lib",
         "@rules_rust//proto:bzl_lib",
         "@rules_rust//rust:bzl_lib",
         "@rules_rust//wasm_bindgen:bzl_lib",
@@ -197,9 +200,16 @@ stardoc(
 )
 
 stardoc(
-    name = "crate_universe",
+    name = "crate_universe_workspace",
     out = "crate_universe.md",
-    input = "@rules_rust//crate_universe:docs.bzl",
+    input = "@rules_rust//crate_universe:docs_workspace.bzl",
+    deps = [":all_docs"],
+)
+
+stardoc(
+    name = "crate_universe_bzlmod",
+    out = "crate_universe_bzlmod.md",
+    input = "@rules_rust//crate_universe:docs_bzlmod.bzl",
     deps = [":all_docs"],
 )
 

docs/MODULE.bazel

@@ -1,6 +1,12 @@
-###############################################################################
-# Bazel now uses Bzlmod by default to manage external dependencies.
-# Please consider migrating your external dependencies from WORKSPACE to MODULE.bazel.
-#
-# For more details, please check https://github.com/bazelbuild/bazel/issues/18958
-###############################################################################
+bazel_dep(
+    name = "bazel_skylib",
+    version = "1.7.1",
+)
+bazel_dep(
+    name = "stardoc",
+    version = "0.6.2",
+)
+bazel_dep(
+    name = "bazel_features",
+    version = "1.11.0",
+)

docs/WORKSPACE.bazel

@@ -36,22 +36,3 @@ load(
 rust_wasm_bindgen_dependencies()
 
 rust_wasm_bindgen_register_toolchains()
-
-load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
-
-http_archive(
-    name = "io_bazel_stardoc",
-    patches = [
-        # Pull in https://github.com/bazelbuild/stardoc/pull/143
-        "//:stardoc-attr-default-wrappers.patch",
-    ],
-    sha256 = "dfbc364aaec143df5e6c52faf1f1166775a5b4408243f445f44b661cfdc3134f",
-    urls = [
-        "https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/0.5.6/stardoc-0.5.6.tar.gz",
-        "https://github.com/bazelbuild/stardoc/releases/download/0.5.6/stardoc-0.5.6.tar.gz",
-    ],
-)
-
-load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories")
-
-stardoc_repositories()