bazel: monitoring docs gen (#54965)

### Changes
improve `write_generated_to_source_files` to:
- allow prefixes to be stripped from generated files
- specify a different destination
- handle being called from a different package than being next to the
src target

This seemed like an easy change on the outset but it turned out to be
quite involved. Some of the problems I encountered while doing this
which required the above changes:

* monitoring-generator copies to a total different path in the repo
route than what it normally outputs - ie. docs/alerts.md,
docs/dashboard.md -> doc/admin/observability/
* `//monitoring:generate_config` outputs are local to it and AFAIK you
can copy/move files to the parent package/dir
* The `//monitoring:generate_config` already does 90% of what we needed,
but the outputs needed to be massaged a bit to fit out use case.
* When one target calls another target in a macro and they're not in the
same package, the "outside" targets outputs will have it's package name
prepended. Which is why we use `root_paths` during copy to have the
copied file paths the same as if the target was called in the same
package
Example:
```
bazel run //:write_monitoring_docs
-> calls //monitoring:generate_config
-> results in outputs being available under `bazel-out/.../monitoring/outputs/`

bazel run //monitoring:write_monitoring_docs
-> calls //monitoring:generate_config
-> results in outputs  being available under `bazel-out/.../outputs/
```


## Test plan
run locally

- [ ] Other generated targets still work
<!-- All pull requests REQUIRE a test plan:
https://docs.sourcegraph.com/dev/background-information/testing_principles
-->

BUILD.bazel

@@ -11,6 +11,7 @@ load("//dev/linters/staticcheck:analyzers.bzl", "STATIC_CHECK_ANALYZERS")
 load("@npm//:eslint/package_json.bzl", eslint_bin = "bin")
 load("//:stamp_tags.bzl", "stamp_tags")
 load("//dev:eslint.bzl", "eslint_test_with_types")
+load("//dev:write_generated_to_source_files.bzl", "write_generated_to_source_files")
 
 # Gazelle config
 #
@@ -328,8 +329,3 @@ exports_files([
     # under certain conditions. See //ui/assets/...
     "CONTRIBUTING.md",
 ])
-
-# stamp_tags(
-#     name = "tags",
-#     remote_tags = ["""($stamp.STABLE_VERSION // "0.0.0")"""],
-# )

dev/BUILD.bazel

@@ -11,11 +11,12 @@ exports_files(srcs = ["eslint-report-test.sh"])
 write_source_files(
     name = "write_all_generated",
     additional_update_targets = [
-        "//lib/codeintel/lsif/protocol:write_symbol_kind",
-        "//lib/codeintel/lsif/protocol:write_symbol_tag",
-        "//internal/batches/search/syntax:write_token_type",
+        "//cmd/cody-gateway/internal/dotcom:write_genql_yaml",
+        "//doc/admin/observability:write_monitoring_docs",
         "//doc/cli/references:write_doc_files",
         "//enterprise/cmd/frontend/internal/guardrails/dotcom:write_genql_yaml",
-        "//cmd/cody-gateway/internal/dotcom:write_genql_yaml",
+        "//internal/batches/search/syntax:write_token_type",
+        "//lib/codeintel/lsif/protocol:write_symbol_kind",
+        "//lib/codeintel/lsif/protocol:write_symbol_tag",
     ],
 )

dev/write_generated_to_source_files.bzl

@@ -1,19 +1,17 @@
 load("@aspect_bazel_lib//lib:directory_path.bzl", "make_directory_path")
 load("@aspect_bazel_lib//lib:copy_to_directory.bzl", "copy_to_directory")
 load("@aspect_bazel_lib//lib:write_source_files.bzl", "write_source_files")
+load("@bazel_skylib//lib:paths.bzl", "paths")
 
-def write_generated_to_source_files(name, src, files, **kwargs):
+def write_generated_to_source_files(name, src, files, strip_prefix = "", verbose_copy=False, **kwargs):
     # We use a copy_to_directory macro so write_source_files inputs and outputs are not at the same
     # path, which enables the write_doc_files_diff_test to work.
-    copy_to_directory(
-        name = "copy_" + name,
-        srcs = [src]
-    )
+    copy_to_directory(name="copy_"+name, srcs=[src], verbose=verbose_copy)
 
     write_source_files(
         name = name,
-        files = {
-            out: make_directory_path(
+        files =  {
+            out.removeprefix(strip_prefix): make_directory_path(
                 out + "_directory_path",
                 "copy_" + name,
                 out,

doc/BUILD.bazel

@@ -6,6 +6,7 @@ sh_test(
     args = ["$(location //dev/tools:docsite)"],
     data = [
         "//dev/tools:docsite",
+        "//doc/admin/observability:doc_files",
         "//doc/cli/references:doc_files",
     ] + glob(
         ["**/*"],

doc/admin/observability/BUILD.bazel

@@ -0,0 +1,28 @@
+load("//dev:write_generated_to_source_files.bzl", "write_generated_to_source_files")
+
+filegroup(
+    name = "doc_files",
+    srcs = glob(
+        ["**/*"],
+        [
+            ".gitattributes",
+        ],
+    ),
+    visibility = ["//doc:__pkg__"],
+)
+
+write_generated_to_source_files(
+    name = "write_monitoring_docs",
+    src = "//monitoring:generate_config",
+    # :generate_config creates an outputs folder with:
+    # - grafana dashboards
+    # - prometheus config
+    # - docs describing dashboards and alerts
+    files = [
+        "monitoring/outputs/docs/alerts.md",
+        "monitoring/outputs/docs/dashboards.md",
+    ],
+    # since :generate_config stores all the generated files under monitroing/outputs when outside of the monitoring package
+    strip_prefix = "monitoring/outputs/docs/",
+    tags = ["go_generate"],
+)

monitoring/main.go

@@ -1,5 +1,9 @@
-//go:generate go build -o /tmp/monitoring-generator
-//go:generate /tmp/monitoring-generator
+// The monitoring generator is now called by Bazel targets instead of go generate
+//
+// To run monitoring generator run:
+// - bazel build //monitoring:generate_config # see bazel-bin/monitoring/outputs
+// - bazel build //monitoring:generate_config_zip # see bazel-bin/monitoring/monitoring.zip
+// - bazel build //monitoring:generate_grafana_config_tar # see bazel-bin/monitoring/monitoring.tar
 package main
 
 import (