Set up docs

.bazelrc

@@ -1,5 +1,6 @@
 common --incompatible_strict_action_env
 common --incompatible_enable_proto_toolchain_resolution
+common --test_output=errors
 
 common --java_runtime_version=remotejdk_21
 common --java_language_version=21

BUILD.bazel

@@ -9,7 +9,7 @@ bzl_library(
 
 exports_files(
     ["bazel_env.bzl"],
-    visibility = ["//visibility:public"],
+    visibility = ["//docs:__pkg__"],
 )
 
 exports_files(

bazel_env.bzl

@@ -331,7 +331,9 @@ _bazel_env_rule = rule(
     executable = True,
 )
 
-def bazel_env(name, *, tools = {}, toolchains = {}, tags = [], visibility = ["//visibility:private"]):
+_FORBIDDEN_TOOL_NAMES = ["direnv", "bazel", "bazelisk"]
+
+def bazel_env(*, name, tools = {}, toolchains = {}, **kwargs):
     # type: (string, dict[string, string | Label], dict[string, string | Label]) -> None
     tool_targets = []
     toolchain_targets = []
@@ -363,14 +365,16 @@ def bazel_env(name, *, tools = {}, toolchains = {}, tags = [], visibility = ["//
     for tool_name, tool in tools.items():
         if not tool_name:
             fail("empty tool names are not allowed")
-        kwargs = {}
+        if tool_name in _FORBIDDEN_TOOL_NAMES:
+            fail("tool name '{}' is forbidden".format(tool_name))
+        tool_kwargs = {}
         is_str = type(tool) == type("")
         if is_str and "$" in tool:
-            kwargs["path"] = tool
+            tool_kwargs["path"] = tool
         elif is_str and tool.startswith("/") and not tool.startswith("//"):
             fail("absolute paths are not supported, got '{}' for tool '{}'".format(tool, tool_name))
         else:
-            kwargs["target"] = tool
+            tool_kwargs["target"] = tool
 
         tool_target_name = name + "/bin/" + tool_name
         tool_targets.append(tool_target_name)
@@ -380,11 +384,11 @@ def bazel_env(name, *, tools = {}, toolchains = {}, tags = [], visibility = ["//
             toolchain_targets = reversed_toolchains,
             visibility = ["//visibility:private"],
             tags = ["manual"],
-            **kwargs
+            **tool_kwargs
         )
 
     for toolchain_name, toolchain in toolchains.items():
-        if not tool_name:
+        if not toolchain_name:
             fail("empty toolchain names are not allowed")
         toolchain_target_name = name + "/toolchains/" + toolchain_name
         toolchain_targets.append(toolchain_target_name)
@@ -400,6 +404,5 @@ def bazel_env(name, *, tools = {}, toolchains = {}, tags = [], visibility = ["//
         unique_name_tool = unique_name_tool,
         tool_targets = tool_targets,
         toolchain_targets = toolchain_targets,
-        tags = tags,
-        visibility = visibility,
+        **kwargs,
     )

docs-gen/BUILD.bazel

@@ -0,0 +1,4 @@
+exports_files(
+    glob(["*.md"]),
+    visibility = ["//docs:__pkg__"],
+)

docs-gen/bazel_env.md

@@ -0,0 +1,25 @@
+<!-- Generated with Stardoc: http://skydoc.bazel.build -->
+
+
+
+<a id="bazel_env"></a>
+
+## bazel_env
+
+<pre>
+bazel_env(<a href="#bazel_env-name">name</a>, <a href="#bazel_env-tools">tools</a>, <a href="#bazel_env-toolchains">toolchains</a>, <a href="#bazel_env-kwargs">kwargs</a>)
+</pre>
+
+
+
+**PARAMETERS**
+
+
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="bazel_env-name"></a>name |  <p align="center"> - </p>   |  none |
+| <a id="bazel_env-tools"></a>tools |  <p align="center"> - </p>   |  `{}` |
+| <a id="bazel_env-toolchains"></a>toolchains |  <p align="center"> - </p>   |  `{}` |
+| <a id="bazel_env-kwargs"></a>kwargs |  <p align="center"> - </p>   |  none |
+
+

docs/BUILD.bazel

@@ -1,3 +1,4 @@
+load("@bazel_skylib//rules:diff_test.bzl", "diff_test")
 load("@rules_proto//proto:proto_lang_toolchain.bzl", "proto_lang_toolchain")
 load("@stardoc//stardoc:stardoc.bzl", "stardoc")
 
@@ -8,6 +9,22 @@ stardoc(
     deps = ["//:bazel_env"],
 )
 
+diff_test(
+    name = "bazel_env_test",
+    failure_message = "Please run:\n    bazel run //docs:update",
+    file1 = "bazel_env.md",
+    file2 = "//docs-gen:bazel_env.md",
+)
+
+sh_binary(
+    name = "update",
+    srcs = ["update.sh"],
+    data = [
+        ":bazel_env",
+    ],
+)
+
+# Precompiled proto toolchain for stardoc
 proto_lang_toolchain(
     name = "protoc_java_toolchain",
     command_line = "--java_out=$(OUT)",

docs/update.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+cd "$BUILD_WORKSPACE_DIRECTORY"
+
+bazel build $(bazel query 'kind(stardoc, //docs:all)')
+
+cp -fv bazel-bin/docs/bazel_env.md docs-gen/bazel_env.md