separate exposing bzl_librarys and rendering docs

lumping these together forced strict toolchain-specific dependencies on
all users, while these are normally only needed for development (in this
case, rendering documentation only).

core/BUILD.bazel

@@ -1,4 +1,4 @@
-load("//docs:stardoc.bzl", "generate")
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 
 package(default_visibility = ["//visibility:public"])
 
@@ -8,16 +8,25 @@ filegroup(
     visibility = ["//visibility:public"],
 )
 
-generate(
-    name = "README.md",
-    inputs = [
+# necessary boilerplate: to build a Bazel library, we always need to include
+# `bazel_tools` as a dependency.
+# https://github.com/bazelbuild/skydoc/issues/166
+# https://github.com/bazelbuild/stardoc/issues/38#issuecomment-568909109
+bzl_library(
+    name = "bazel_tools",
+    srcs = [
+        "@bazel_tools//tools:bzl_srcs",
+    ],
+)
+
+bzl_library(
+    name = "nixpkgs",
+    srcs = [
         "nixpkgs.bzl",
         "util.bzl",
     ],
-    symbol_names = [
-        "nixpkgs_git_repository",
-        "nixpkgs_local_repository",
-        "nixpkgs_package",
+    deps = [
+        ":bazel_tools",
+        "@bazel_skylib//lib:paths",
     ],
-    deps = ["@bazel_skylib//lib:paths"],
 )

core/docs/BUILD.bazel

@@ -1,5 +1,18 @@
+load(":stardoc.bzl", "generate_documentation")
+
 exports_files([
     "stardoc.bzl",
     "copy-files.sh",
     "compare-files.sh",
 ] + glob(["templates/*"]))
+
+generate_documentation(
+    name = "README.md",
+    input = "//:nixpkgs.bzl",
+    symbol_names = [
+        "nixpkgs_git_repository",
+        "nixpkgs_local_repository",
+        "nixpkgs_package",
+    ],
+    deps = ["//:nixpkgs"],
+)

core/docs/compare-files.sh

@@ -4,6 +4,7 @@ set -euo pipefail
 # print error message (set in `$errormsg` environment variable) and exit if any
 # pair does not have equal contents.
 while (($#)); do
+  # impurity: our special setup requires that the second file is at the top level of a workspace.
   if ! cmp -s "$1" "$2"; then
     echo "$errormsg"
     exit 1

core/docs/stardoc.bzl

@@ -1,56 +1,29 @@
-load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 load("@io_bazel_stardoc//stardoc:stardoc.bzl", _stardoc = "stardoc")
 
-def generate(
+def generate_documentation(
         name,
-        inputs,
+        input,
         error_message = None,
-        deps = [],
         **kwargs):
     """
-    full-service documentation rendering
-
-    - make a Bazel library from `inputs`
-    - create rules for
-        - generating library documentation
-        - copying a file into the source tree containing it
-        - testing that the copying has actually happened
-          (since the copy rule must be run manually)
+    rules for rendering library documentation
 
-    NOTE: library name is derived from first file in `inputs`, without extensions.
+    creates rules for
+    - generating library documentation
+    - copying a file into the source tree containing it
+    - testing that the copying has actually happened
+        (since the copy rule must be run manually)
 
     Args:
         name: target file name for rendered documentation.
-        inputs: file names for Bazel library and documentation
+        input: file name to render documentation from
         error_message: custom error message to print if rendered documentation is not up to date.
-        deps: library dependencies of the `inputs` provided.
         **kwargs: arguments for `stardoc`, most notably `symbol_names` to generate documentation for.
     """
 
-    # necessary boilerplate: to build a Bazel library, we always need to include
-    # `bazel_tools` as a dependency.
-    # since we will combine toolchain libraries with the core library, but only
-    # need `bazel_tools` dependency once, only create if not already there.
-    if not native.existing_rule("bazel_tools"):
-        bzl_library(
-            name = "bazel_tools",
-            srcs = [
-                "@bazel_tools//tools:bzl_srcs",
-            ],
-        )
-
-    # massage first input file name into nice rule name
-    lib = Label(absolute_label(inputs[0])).name.split(".")[0]
-    bzl_library(
-        name = lib,
-        srcs = inputs,
-        visibility = ["//visibility:public"],
-        deps = [":bazel_tools"] + deps,
-    )
-
     # generate documentation into transient file
     out = "_{}".format(name)
-    stardoc("__{}".format(name), out, inputs[0], deps = [lib], **kwargs)
+    stardoc("__{}".format(name), out, input, **kwargs)
 
     # create rule to copy documentation into source tree
     # has to be run manually! set up a commit hook for convenience?

docs/BUILD.bazel

@@ -1,8 +1,8 @@
-load("@rules_nixpkgs_core//docs:stardoc.bzl", "generate")
+load("@rules_nixpkgs_core//docs:stardoc.bzl", "generate_documentation")
 
-generate(
+generate_documentation(
     name = "README.md",
-    inputs = ["//nixpkgs:nixpkgs.bzl"],
+    input = "//nixpkgs:nixpkgs.bzl",
     symbol_names = [
         "nixpkgs_git_repository",
         "nixpkgs_local_repository",
@@ -16,17 +16,7 @@ generate(
         "nixpkgs_sh_posix_configure",
     ],
     deps = [
-        "@bazel_skylib//lib:new_sets",
-        "@bazel_skylib//lib:paths",
-        "@bazel_skylib//lib:sets",
-        "@bazel_skylib//lib:versions",
-        "@rules_nixpkgs_cc//:cc",
-        "@rules_nixpkgs_core//:nixpkgs",
-        "@rules_nixpkgs_go//:go",
-        "@rules_nixpkgs_java//:java",
-        "@rules_nixpkgs_posix//:posix",
-        "@rules_nixpkgs_python//:python",
-        "@rules_nixpkgs_rust//:rust",
+        "//nixpkgs",
     ],
 )
 

nixpkgs/BUILD.bazel

@@ -1,7 +1,28 @@
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+
 package(default_visibility = ["//visibility:public"])
 
 filegroup(
     name = "srcs",
     srcs = glob(["**"]),
     visibility = ["//visibility:public"],
 )
+
+bzl_library(
+    name = "nixpkgs",
+    srcs = ["nixpkgs.bzl"],
+    deps = [
+        "@bazel_skylib//lib:new_sets",
+        "@bazel_skylib//lib:paths",
+        "@bazel_skylib//lib:sets",
+        "@bazel_skylib//lib:versions",
+        "@rules_nixpkgs_cc//:cc",
+        "@rules_nixpkgs_core//:bazel_tools",
+        "@rules_nixpkgs_core//:nixpkgs",
+        "@rules_nixpkgs_go//:go",
+        "@rules_nixpkgs_java//:java",
+        "@rules_nixpkgs_posix//:posix",
+        "@rules_nixpkgs_python//:python",
+        "@rules_nixpkgs_rust//:rust",
+    ],
+)

toolchains/cc/BUILD.bazel

@@ -1,4 +1,4 @@
-load("@rules_nixpkgs_core//docs:stardoc.bzl", "generate")
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 
 package(default_visibility = ["//visibility:public"])
 
@@ -8,17 +8,15 @@ filegroup(
     visibility = ["//visibility:public"],
 )
 
-generate(
-    name = "README.md",
-    inputs = ["//:cc.bzl"],
-    symbol_names = [
-        "nixpkgs_cc_configure",
-    ],
+bzl_library(
+    name = "cc",
+    srcs = ["cc.bzl"],
     deps = [
         "@bazel_skylib//lib:new_sets",
         "@bazel_skylib//lib:paths",
         "@bazel_skylib//lib:sets",
         "@bazel_skylib//lib:versions",
+        "@rules_nixpkgs_core//:bazel_tools",
         "@rules_nixpkgs_core//:nixpkgs",
     ],
 )

toolchains/cc/docs/BUILD.bazel

@@ -0,0 +1,8 @@
+load("@rules_nixpkgs_core//docs:stardoc.bzl", "generate_documentation")
+
+generate_documentation(
+    name = "README.md",
+    input = "//:cc.bzl",
+    symbol_names = ["nixpkgs_cc_configure"],
+    deps = ["//:cc"],
+)

toolchains/go/BUILD.bazel

@@ -1,4 +1,4 @@
-load("@rules_nixpkgs_core//docs:stardoc.bzl", "generate")
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 
 package(default_visibility = ["//visibility:public"])
 
@@ -8,12 +8,9 @@ filegroup(
     visibility = ["//visibility:public"],
 )
 
-generate(
-    name = "README.md",
-    inputs = ["//:go.bzl"],
-    symbol_names = [
-        "nixpkgs_go_configure",
-    ],
+bzl_library(
+    name = "go",
+    srcs = ["//:go.bzl"],
     deps = [
         "@io_bazel_rules_go//go:deps",
         "@rules_nixpkgs_core//:nixpkgs",

toolchains/go/WORKSPACE

@@ -0,0 +1,42 @@
+# NOTE: temporary boilerplate for compatibility with `WORKSPACE` setup!
+# TODO: remove when migration to `bzlmod` is complete
+
+### generic dependencies for rendering documentation
+
+local_repository(
+    name = "io_tweag_rules_nixpkgs",
+    path = "../..",
+)
+
+load("@io_tweag_rules_nixpkgs//nixpkgs:repositories.bzl", "rules_nixpkgs_dependencies")
+
+rules_nixpkgs_dependencies()
+
+load("@rules_nixpkgs_core//docs:dependencies_1.bzl", "docs_dependencies_1")
+
+docs_dependencies_1()
+
+load("@rules_nixpkgs_core//docs:dependencies_2.bzl", "docs_dependencies_2")
+
+docs_dependencies_2()
+
+### end generic dependencies for rendering documentation
+
+load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+
+http_archive(
+    name = "io_bazel_rules_go",
+    sha256 = "7c10271940c6bce577d51a075ae77728964db285dac0a46614a7934dc34303e6",
+    urls = [
+        "https://mirror.bazel.build/github.com/bazelbuild/rules_go/releases/download/v0.26.0/rules_go-v0.26.0.tar.gz",
+        "https://github.com/bazelbuild/rules_go/releases/download/v0.26.0/rules_go-v0.26.0.tar.gz",
+    ],
+)
+
+load("//:go.bzl", "nixpkgs_go_configure")
+
+nixpkgs_go_configure(repository = "@nixpkgs")
+
+load("@io_bazel_rules_go//go:deps.bzl", "go_rules_dependencies")
+
+go_rules_dependencies()

toolchains/go/docs/BUILD.bazel

@@ -0,0 +1,8 @@
+load("@rules_nixpkgs_core//docs:stardoc.bzl", "generate_documentation")
+
+generate_documentation(
+    name = "README.md",
+    input = "//:go.bzl",
+    symbol_names = ["nixpkgs_go_configure"],
+    deps = ["//:go"],
+)

toolchains/java/BUILD.bazel

@@ -1,4 +1,4 @@
-load("@rules_nixpkgs_core//docs:stardoc.bzl", "generate")
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 
 package(default_visibility = ["//visibility:public"])
 
@@ -8,11 +8,10 @@ filegroup(
     visibility = ["//visibility:public"],
 )
 
-generate(
-    name = "README.md",
-    inputs = ["//:java.bzl"],
-    symbol_names = [
-        "nixpkgs_java_configure",
+bzl_library(
+    name = "java",
+    srcs = ["//:java.bzl"],
+    deps = [
+        "@rules_nixpkgs_core//:nixpkgs",
     ],
-    deps = ["@rules_nixpkgs_core//:nixpkgs"],
 )

toolchains/java/docs/BUILD.bazel

@@ -0,0 +1,8 @@
+load("@rules_nixpkgs_core//docs:stardoc.bzl", "generate_documentation")
+
+generate_documentation(
+    name = "README.md",
+    input = "//:java.bzl",
+    symbol_names = ["nixpkgs_java_configure"],
+    deps = ["//:java"],
+)

toolchains/posix/BUILD.bazel

@@ -1,4 +1,4 @@
-load("@rules_nixpkgs_core//docs:stardoc.bzl", "generate")
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 
 package(default_visibility = ["//visibility:public"])
 
@@ -8,12 +8,9 @@ filegroup(
     visibility = ["//visibility:public"],
 )
 
-generate(
-    name = "README.md",
-    inputs = ["//:posix.bzl"],
-    symbol_names = [
-        "nixpkgs_sh_posix_configure",
-    ],
+bzl_library(
+    name = "posix",
+    srcs = ["//:posix.bzl"],
     deps = [
         "@rules_nixpkgs_core//:nixpkgs",
     ],

toolchains/posix/docs/BUILD.bazel

@@ -0,0 +1,8 @@
+load("@rules_nixpkgs_core//docs:stardoc.bzl", "generate_documentation")
+
+generate_documentation(
+    name = "README.md",
+    input = "//:posix.bzl",
+    symbol_names = ["nixpkgs_sh_posix_configure"],
+    deps = ["//:posix"],
+)

toolchains/python/BUILD.bazel

@@ -1,4 +1,4 @@
-load("@rules_nixpkgs_core//docs:stardoc.bzl", "generate")
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 
 package(default_visibility = ["//visibility:public"])
 
@@ -8,12 +8,9 @@ filegroup(
     visibility = ["//visibility:public"],
 )
 
-generate(
-    name = "README.md",
-    inputs = ["//:python.bzl"],
-    symbol_names = [
-        "nixpkgs_python_configure",
-    ],
+bzl_library(
+    name = "python",
+    srcs = ["//:python.bzl"],
     deps = [
         "@bazel_skylib//lib:versions",
         "@rules_nixpkgs_core//:nixpkgs",