docs: produce API docs for rules in the @npm repo (#1236)

* docs: produce API docs for rules in the @npm repo

* fix formatting

* fix formatting

* rename: npm_link_all_packages.md

docs/BUILD.bazel

@@ -40,6 +40,11 @@ stardoc_with_diff_test(
     bzl_library_target = "//npm/private:npm_link_package",
 )
 
+stardoc_with_diff_test(
+    name = "npm_link_all_packages",
+    bzl_library_target = "//npm/private:npm_translate_lock_generate.docs",
+)
+
 stardoc_with_diff_test(
     name = "npm_import",
     bzl_library_target = "//npm/private:npm_import",

docs/pnpm.md

@@ -26,7 +26,7 @@ You may wish to read the [generated API documentation](/docs/npm_import.md#npm_t
 As a high level overview, the primary rules and targets used by developers to fetch and link npm package dependencies are:
 
 -   [`npm_translate_lock()`](/docs/npm_import.md#npm_translate_lock) - generate targets representing packages from a pnpm lockfile.
--   [`npm_link_all_packages()`](/docs/npm_link_all_packages.md#npm_link_all_packages) - defines a `node_modules` tree and the associated `node_modules/{package}` targets. This rule is required in the BUILD file of each package in the pnpm workspace that has npm packages linked into a `node_modules` folder as well the BUILD file of the package that corresponds to the root of the pnpm workspace where the pnpm lock file resides.
+-   [`npm_link_all_packages()`](/docs/npm_link_all_packages.md) - defines a `node_modules` tree and the associated `node_modules/{package}` targets. This rule is required in the BUILD file of each package in the pnpm workspace that has npm packages linked into a `node_modules` folder as well the BUILD file of the package that corresponds to the root of the pnpm workspace where the pnpm lock file resides.
 -   `:node_modules/{package}` - targets generated by `npm_link_all_packages()` representing each package dependency from a `package.json` within the pnpm workspace.
 
 For example:

npm/private/BUILD.bazel

@@ -1,5 +1,6 @@
 "Internal implementation details"
 
+load("@aspect_bazel_lib//lib:testing.bzl", "assert_contains")
 load("@aspect_rules_js//js:defs.bzl", "js_library")
 load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 
@@ -19,6 +20,24 @@ exports_files(
     visibility = ["//visibility:public"],
 )
 
+# We manually keep the generated rules documentation synced.
+# Check that the signatures stay matched.
+[
+    assert_contains(
+        name = "_test_gendocs_{}_{}".format(i, j),
+        actual = actual,
+        expected = expected,
+    )
+    for i, actual in enumerate([
+        "npm_translate_lock_generate.bzl",
+        "npm_translate_lock_generate.docs.bzl",
+    ])
+    for j, expected in enumerate([
+        """def npm_link_targets(name = "node_modules", package = None):""",
+        """def npm_link_all_packages(name = "node_modules", imported_links = []):""",
+    ])
+]
+
 bzl_library(
     name = "npm_package",
     srcs = ["npm_package.bzl"],
@@ -185,18 +204,6 @@ bzl_library(
     ],
 )
 
-bzl_library(
-    name = "npmrc",
-    srcs = ["npmrc.bzl"],
-    visibility = ["//npm:__subpackages__"],
-)
-
-bzl_library(
-    name = "pkg_glob",
-    srcs = ["pkg_glob.bzl"],
-    visibility = ["//npm:__subpackages__"],
-)
-
 bzl_library(
     name = "utils",
     srcs = ["utils.bzl"],
@@ -272,6 +279,24 @@ bzl_library(
     visibility = ["//npm:__subpackages__"],
 )
 
+bzl_library(
+    name = "npm_translate_lock_generate.docs",
+    srcs = ["npm_translate_lock_generate.docs.bzl"],
+    visibility = ["//docs:__pkg__"],
+)
+
+bzl_library(
+    name = "npmrc",
+    srcs = ["npmrc.bzl"],
+    visibility = ["//npm:__subpackages__"],
+)
+
+bzl_library(
+    name = "pkg_glob",
+    srcs = ["pkg_glob.bzl"],
+    visibility = ["//npm:__subpackages__"],
+)
+
 bzl_library(
     name = "starlark_codegen_utils",
     srcs = ["starlark_codegen_utils.bzl"],

npm/private/npm_translate_lock.bzl

@@ -181,9 +181,11 @@ def npm_translate_lock(
     containing a helper starlark module `repositories.bzl`, which supplies a loadable macro
     `npm_repositories`. That macro creates an `npm_import` for each package.
 
-    The generated repository also contains `BUILD` files declaring targets for the packages
-    listed as `dependencies` or `devDependencies` in `package.json`, so you can declare
-    dependencies on those packages without having to repeat version information.
+    The generated repository also contains:
+
+    - A `defs.bzl` file containing some rules such as `npm_link_all_packages`, which are [documented here](./npm_link_all_packages.md).
+    - `BUILD` files declaring targets for the packages listed as `dependencies` or `devDependencies` in `package.json`,
+      so you can declare dependencies on those packages without having to repeat version information.
 
     This macro creates a `pnpm` external repository, if the user didn't create a repository named
     "pnpm" prior to calling `npm_translate_lock`.

npm/private/npm_translate_lock_generate.bzl

@@ -767,20 +767,8 @@ sh_binary(
 load("@aspect_rules_js//npm/private:npm_package_store.bzl", _npm_package_store = "npm_package_store")""")
 
     npm_link_targets_bzl = [
-        """def npm_link_targets(name = "node_modules", package = None):
-    \"\"\"Generated list of target names that are linked by npm_link_all_packages()
-
-    Args:
-        name: name of catch all target to generate for all packages linked
-        package: Bazel package to generate targets names for.
-
-            Set to an empty string "" to specify the root package.
-
-            If unspecified, the current package (`native.package_name()`) is used.
-
-    Returns:
-        A list of target names that are linked by npm_link_all_packages()
-    \"\"\"
+        """\
+def npm_link_targets(name = "node_modules", package = None):
     link_packages = {link_packages}
     bazel_package = package if package != None else native.package_name()
     link = bazel_package in link_packages
@@ -790,28 +778,8 @@ load("@aspect_rules_js//npm/private:npm_package_store.bzl", _npm_package_store =
     ]
 
     npm_link_all_packages_bzl = [
-        """def npm_link_all_packages(name = "node_modules", imported_links = []):
-    \"\"\"Generated list of npm_link_package() target generators and first-party linked packages corresponding to the packages in {pnpm_lock_label}
-
-    Args:
-        name: name of catch all target to generate for all packages linked
-        imported_links: optional list link functions from manually imported packages
-            that were fetched with npm_import rules,
-
-            For example,
-
-            ```
-            load("@npm//:defs.bzl", "npm_link_all_packages")
-            load("@npm_meaning-of-life__links//:defs.bzl", npm_link_meaning_of_life = "npm_link_imported_package")
-
-            npm_link_all_packages(
-                name = "node_modules",
-                imported_links = [
-                    npm_link_meaning_of_life,
-                ],
-            )```
-    \"\"\"
-
+        """\
+def npm_link_all_packages(name = "node_modules", imported_links = []):
     root_package = "{root_package}"
     link_packages = {link_packages}
     is_root = native.package_name() == root_package

npm/private/npm_translate_lock_generate.docs.bzl

@@ -0,0 +1,56 @@
+"""\
+Build rules generated by `npm_translate_lock`
+=============================================
+
+These are loaded from the external repository created by `npm_translate_lock` based on the name provided.
+
+For example, if you run `npm_translate_lock(name = "npm")` then these rules can be loaded with
+
+```
+load("@npm//:defs.bzl", "npm_link_targets", "npm_link_all_packages")
+```
+"""
+
+# NOTE: we don't attempt to run stardoc against @npm//:defs.bzl to produce these docstrings
+# because that file load()s from BUILD files in every package, so the bzl_library target required
+# is impossible to write.
+# Instead, we define the interfaces in this file, while the implementations live in npm_translate_lock_generate.bzl.
+
+# buildifier: disable=unused-variable
+def npm_link_targets(name = "node_modules", package = None):
+    """Generated list of target names that are linked by npm_link_all_packages()
+
+    Args:
+        name: name of catch all target to generate for all packages linked
+        package: Bazel package to generate targets names for.
+
+            Set to an empty string "" to specify the root package.
+
+            If unspecified, the current package (`native.package_name()`) is used.
+
+    Returns:
+        A list of target names that are linked by npm_link_all_packages()
+    """
+    pass
+
+# buildifier: disable=unused-variable
+def npm_link_all_packages(name = "node_modules", imported_links = []):
+    """Generated list of npm_link_package() target generators and first-party linked packages corresponding to the packages in {pnpm_lock_label}
+
+    If you use manually-written [`npm_import`](/docs/npm_import.md#npm_import) you can link these as well, for example,
+
+        load("@npm//:defs.bzl", "npm_link_all_packages")
+        load("@npm_meaning-of-life__links//:defs.bzl", npm_link_meaning_of_life = "npm_link_imported_package")
+
+        npm_link_all_packages(
+            name = "node_modules",
+            imported_links = [
+                npm_link_meaning_of_life,
+            ],
+        )
+
+    Args:
+        name: name of catch all target to generate for all packages linked
+        imported_links: optional list link functions from manually imported packages that were fetched with npm_import rules.
+    """
+    pass