[maintenance] Move all docs-related targets to the docs folder, mark stardoc as a dev dependency (#1435)

Author: agluszak

.bazelci/presubmit.yml

@@ -73,7 +73,7 @@ tasks:
     name: Stardoc api documentation
     platform: rbe_ubuntu2404
     build_targets:
-      - //kotlin:stardoc
+      - //docs:stardoc
     test_targets:
       - //docs/...
   ktlint:

MODULE.bazel

@@ -133,8 +133,8 @@ maven.override(
 use_repo(maven, "kotlin_rules_maven", "unpinned_kotlin_rules_maven")
 
 bazel_dep(name = "rules_pkg", version = "1.0.1")
-bazel_dep(name = "stardoc", version = "0.8.0", repo_name = "io_bazel_stardoc")
 
+bazel_dep(name = "stardoc", version = "0.8.0", dev_dependency = True, repo_name = "io_bazel_stardoc")
 bazel_dep(name = "aspect_bazel_lib", version = "2.22.0", dev_dependency = True)
 bazel_dep(name = "rules_testing", version = "0.9.0", dev_dependency = True)
 bazel_dep(name = "rules_bazel_integration_test", version = "0.34.0", dev_dependency = True)

Makefile

@@ -30,8 +30,7 @@ deps.regen:
 	scripts/regen_deps
 
 docs.regen:
-	bazel build //kotlin:stardoc
-	cp bazel-bin/kotlin/kotlin.md docs/kotlin.md
+	bazel run //docs:write_docs
 
 proto.regen:
 	scripts/gen_proto_jars

docs/BUILD.bazel

@@ -1,8 +1,40 @@
 load("@aspect_bazel_lib//lib:write_source_files.bzl", "write_source_files")
+load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
+
+[
+    stardoc(
+        name = doc,
+        out = "%s.md" % doc,
+        input = "//kotlin:%s.bzl" % doc,
+        deps = [
+            "//kotlin/internal",
+        ],
+    )
+    for doc in [
+        "jvm",
+        "lint",
+        "core",
+        "repositories.doc",
+    ]
+]
+
+genrule(
+    name = "stardoc",
+    srcs = [doc for doc in [
+        "jvm",
+        "lint",
+        "core",
+        "repositories.doc",
+    ]],
+    outs = ["kotlin.md.generated"],
+    cmd = """
+    cat $(SRCS) >> $@
+    """,
+)
 
 write_source_files(
     name = "write_docs",
     files = {
-        "kotlin.md": "//kotlin:stardoc",
+        "kotlin.md": ":stardoc",
     },
 )

kotlin/BUILD

@@ -1,5 +1,3 @@
-load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
-
 # Copyright 2018 The Bazel Authors. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -15,6 +13,13 @@ load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
 # limitations under the License.
 load("//src/main/starlark/release:packager.bzl", "release_archive")
 
+exports_files([
+    "jvm.bzl",
+    "lint.bzl",
+    "core.bzl",
+    "repositories.doc.bzl",
+])
+
 release_archive(
     name = "pkg",
     srcs = glob(
@@ -32,38 +37,3 @@ release_archive(
         "//kotlin/settings:pkg",
     ],
 )
-
-[
-    stardoc(
-        name = doc,
-        out = "%s.md" % doc,
-        input = "%s.bzl" % doc,
-        deps = [
-            "//kotlin/internal",
-        ],
-    )
-    for doc in [
-        "jvm",
-        "lint",
-        "core",
-        "repositories.doc",
-    ]
-]
-
-genrule(
-    name = "stardoc",
-    srcs = [doc for doc in [
-        "jvm",
-        "lint",
-        "core",
-        "repositories.doc",
-    ]],
-    outs = ["kotlin.md"],
-    cmd = """
-    cat $(SRCS) >> $@
-    """,
-    executable = True,
-    visibility = [
-        "//visibility:public",
-    ],
-)

kotlin/internal/BUILD

@@ -37,7 +37,10 @@ release_archive(
 bzl_library(
     name = "internal",
     srcs = glob(["*.bzl"]),
-    visibility = ["//kotlin:__subpackages__"],
+    visibility = [
+        "//docs:__pkg__",
+        "//kotlin:__subpackages__",
+    ],
     deps = [
         "//kotlin/internal/jvm",
         "//kotlin/internal/lint",

scripts/generate_docs

@@ -1,5 +1,3 @@
 #!/usr/bin/env bash
 
-bazel build //kotlin:stardoc || fail "docs did not generate"
-
-cp -f bazel-bin/kotlin/kotlin.md docs/ || fail "couldn't copy"
+bazel run //docs:write_docs || fail "docs did not generate"