chore(docs): document module extensions (#3898)

These are the primary API under bzlmod

Also pull out the docgen snippet so we can call it from a different
pipeline, like I did in rules_ts and rules_js

Author: alexeagle

.github/workflows/release_docs.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Add generated API docs to the release
+# see https://github.com/bazelbuild/bazel-central-registry/blob/main/docs/stardoc.md
+set -o errexit -o nounset -o pipefail
+
+docs="$(mktemp -d)"
+targets="$(mktemp)"
+out=$1
+bazel --output_base="$docs" query --output=label --output_file="$targets" 'kind("starlark_doc_extract rule", //...)'
+bazel --output_base="$docs" build --target_pattern_file="$targets"
+tar --create --auto-compress \
+	--directory "$(bazel --output_base="$docs" info bazel-bin)" \
+	--file "${out}" .

.github/workflows/release_prep.sh

@@ -10,14 +10,7 @@ PREFIX="rules_nodejs-${TAG:1}"
 ARCHIVE="rules_nodejs-$TAG.tar.gz"
 git archive --format=tar --prefix="${PREFIX}/" "${TAG}" | gzip > "$ARCHIVE"
 SHA=$(shasum -a 256 "$ARCHIVE" | awk '{print $1}')
-
-# Add generated API docs to the release, see https://github.com/bazelbuild/bazel-central-registry/issues/5593
-docs="$(mktemp -d)"; targets="$(mktemp)"
-bazel --output_base="$docs" query --output=label --output_file="$targets" 'kind("starlark_doc_extract rule", //...)'
-bazel --output_base="$docs" build --target_pattern_file="$targets" --remote_download_regex='.*doc_extract\.binaryproto'
-tar --create --auto-compress \
-    --directory "$(bazel --output_base="$docs" info bazel-bin)" \
-    --file "$GITHUB_WORKSPACE/${ARCHIVE%.tar.gz}.docs.tar.gz" .
+./.github/workflows/release_docs.sh "$GITHUB_WORKSPACE/${ARCHIVE%.tar.gz}.docs.tar.gz"
 
 cat << EOF
 ## Using Bzlmod with Bazel 6 or greater

WORKSPACE

@@ -16,17 +16,6 @@ workspace(name = "rules_nodejs")
 
 load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
 
-http_archive(
-    name = "bazel_features",
-    sha256 = "5ab1a90d09fd74555e0df22809ad589627ddff263cff82535815aa80ca3e3562",
-    strip_prefix = "bazel_features-1.39.0",
-    url = "https://github.com/bazel-contrib/bazel_features/releases/download/v1.39.0/bazel_features-v1.39.0.tar.gz",
-)
-
-load("@bazel_features//:deps.bzl", "bazel_features_deps")
-
-bazel_features_deps()
-
 #
 # Install rules_nodejs dev dependencies
 #
@@ -35,6 +24,10 @@ load("//:repositories.bzl", "rules_nodejs_dev_dependencies")
 
 rules_nodejs_dev_dependencies()
 
+load("@bazel_features//:deps.bzl", "bazel_features_deps")
+
+bazel_features_deps()
+
 #
 # Setup rules_nodejs npm dependencies
 #
@@ -84,6 +77,10 @@ load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace")
 
 bazel_skylib_workspace()
 
+load("@rules_cc//cc:extensions.bzl", "compatibility_proxy_repo")
+
+compatibility_proxy_repo()
+
 # Buildifier
 load("@buildifier_prebuilt//:deps.bzl", "buildifier_prebuilt_deps")
 

nodejs/BUILD.bazel

@@ -6,6 +6,12 @@ load(":node_toolchain_alias.bzl", "node_runtime_alias", "node_toolchain_alias")
 
 package(default_visibility = ["//visibility:public"])
 
+bzl_library(
+    name = "extensions",
+    srcs = ["extensions.bzl"],
+    deps = [":repositories"],
+)
+
 bzl_library(
     name = "providers",
     srcs = ["providers.bzl"],
@@ -26,6 +32,16 @@ bzl_library(
     ],
 )
 
+bzl_library(
+    name = "toolchain",
+    srcs = ["toolchain.bzl"],
+    deps = [
+        "//nodejs/private:current_node_cc_headers",
+        "//nodejs/private:os_name",
+        "@rules_cc//cc:defs_bzl",
+    ],
+)
+
 # This is the target rule authors should put in their "toolchains"
 # attribute in order to get a node interpreter for the correct
 # platform.

nodejs/extensions.bzl

@@ -1,4 +1,13 @@
-"extensions for bzlmod"
+"""Module extensions for nodejs toolchain registration in MODULE.bazel
+
+Example usage, assuming a `.nvmrc` file is present in the same directory as the `MODULE.bazel` file:
+
+```starlark
+node = use_extension("@rules_nodejs//nodejs:extensions.bzl", "node")
+node.toolchain(node_version_from_nvmrc = "//:.nvmrc")
+use_repo(node, "nodejs_toolchains")
+```
+"""
 
 load(
     ":repositories.bzl",
@@ -67,11 +76,13 @@ _ATTRS = {
         allow_single_file = True,
         doc = """The .nvmrc file containing the version of Node.js to use.
 
+This is recommended to ensure Bazel uses the same Node.js version as non-Bazel tooling.
 If set then the version found in the .nvmrc file is used instead of the one specified by node_version.""",
     ),
     "include_headers": attr.bool(
         doc = """Set headers field in NodeInfo provided by this toolchain.
 
+Required to compile native code into a Node.js binary.
 This setting creates a dependency on a c++ toolchain.
 """,
     ),

repositories.bzl

@@ -30,6 +30,12 @@ def rules_nodejs_dev_dependencies():
     These are in this file to keep version information in one place, and make the WORKSPACE
     shorter.
     """
+    http_archive(
+        name = "bazel_features",
+        sha256 = "5ab1a90d09fd74555e0df22809ad589627ddff263cff82535815aa80ca3e3562",
+        strip_prefix = "bazel_features-1.39.0",
+        url = "https://github.com/bazel-contrib/bazel_features/releases/download/v1.39.0/bazel_features-v1.39.0.tar.gz",
+    )
 
     http_archive(
         name = "bazel_skylib",
@@ -50,3 +56,10 @@ def rules_nodejs_dev_dependencies():
         strip_prefix = "buildifier-prebuilt-8.0.0",
         urls = ["http://github.com/keith/buildifier-prebuilt/archive/8.0.0.tar.gz"],
     )
+
+    http_archive(
+        name = "rules_cc",
+        sha256 = "458b658277ba51b4730ea7a2020efdf1c6dcadf7d30de72e37f4308277fa8c01",
+        strip_prefix = "rules_cc-0.2.16",
+        url = "https://github.com/bazelbuild/rules_cc/releases/download/0.2.16/rules_cc-0.2.16.tar.gz",
+    )