From 535bc3ba6ce0ef20bf2dfcdb741428f82e250ff7 Mon Sep 17 00:00:00 2001
From: Fabian Meumertzheim <fabian@meumertzhe.im>
Date: Fri, 24 May 2024 13:36:54 +0200
Subject: [PATCH] Set up docs

---
 .bazelrc              |  1 +
 BUILD.bazel           |  2 +-
 bazel_env.bzl         | 19 +++++++++++--------
 docs-gen/BUILD.bazel  |  4 ++++
 docs-gen/bazel_env.md | 25 +++++++++++++++++++++++++
 docs/BUILD.bazel      | 17 +++++++++++++++++
 docs/update.sh        |  9 +++++++++
 7 files changed, 68 insertions(+), 9 deletions(-)
 create mode 100644 docs-gen/BUILD.bazel
 create mode 100755 docs-gen/bazel_env.md
 create mode 100755 docs/update.sh

diff --git a/.bazelrc b/.bazelrc
index e6e544a..15a7513 100644
--- a/.bazelrc
+++ b/.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
diff --git a/BUILD.bazel b/BUILD.bazel
index 82a56f9..ecaf40d 100644
--- a/BUILD.bazel
+++ b/BUILD.bazel
@@ -9,7 +9,7 @@ bzl_library(
 
 exports_files(
     ["bazel_env.bzl"],
-    visibility = ["//visibility:public"],
+    visibility = ["//docs:__pkg__"],
 )
 
 exports_files(
diff --git a/bazel_env.bzl b/bazel_env.bzl
index 623ec41..b0fb9c9 100644
--- a/bazel_env.bzl
+++ b/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,
     )
diff --git a/docs-gen/BUILD.bazel b/docs-gen/BUILD.bazel
new file mode 100644
index 0000000..8e5aaeb
--- /dev/null
+++ b/docs-gen/BUILD.bazel
@@ -0,0 +1,4 @@
+exports_files(
+    glob(["*.md"]),
+    visibility = ["//docs:__pkg__"],
+)
diff --git a/docs-gen/bazel_env.md b/docs-gen/bazel_env.md
new file mode 100755
index 0000000..416f672
--- /dev/null
+++ b/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 |
+
+
diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel
index 6aa9994..7678b68 100644
--- a/docs/BUILD.bazel
+++ b/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)",
diff --git a/docs/update.sh b/docs/update.sh
new file mode 100755
index 0000000..a6a27ab
--- /dev/null
+++ b/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