feat: improve our docs generation

Move out of stardoc and start using something supported by BCR as
suggested by https://github.com/bazelbuild/bazel-central-registry/blob/main/docs/stardoc.md

Author: manuelnaranjo

.github/workflows/release_prep.sh

@@ -62,6 +62,14 @@ tar --file $ARCHIVE_TMP --append ${PREFIX}/MODULE.bazel
 gzip < $ARCHIVE_TMP > $ARCHIVE
 SHA=$(shasum -a 256 $ARCHIVE | awk '{print $1}')
 
+# Add generated API docs to the release, see https://github.com/bazelbuild/bazel-central-registry/issues/5593
+docs="$(mktemp -d)"; targets="$(mktemp)"
+bazel --output_base="$docs" query --output=label --output_file="$targets" 'kind("starlark_doc_extract rule", //...)'
+bazel --output_base="$docs" build --target_pattern_file="$targets"
+tar --create --auto-compress \
+    --directory "$(bazel --output_base="$docs" info bazel-bin)" \
+    --file "$GITHUB_WORKSPACE/${ARCHIVE%.tar.gz}.docs.tar.gz" .
+
 # Set by GH actions, see
 # https://docs.github.com/en/actions/learn-github-actions/environment-variables#default-environment-variables
 REPO_URL="${GITHUB_REPOSITORY:-rmohr/bazeldnf}"

BUILD.bazel

@@ -1,4 +1,4 @@
-load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+load("@bazel_lib//:bzl_library.bzl", "bzl_library")
 load("@buildifier_prebuilt//:rules.bzl", "buildifier")
 load("@gazelle//:def.bzl", "gazelle", "gazelle_binary")
 load("@rules_cc//cc:defs.bzl", "cc_library")
@@ -18,6 +18,7 @@ gazelle_binary(
 # gazelle:prefix github.com/rmohr/bazeldnf
 # gazelle:resolve go github.com/bazelbuild/buildtools/build @com_github_bazelbuild_buildtools//build:go_default_library
 # gazelle:resolve go github.com/bazelbuild/buildtools/edit @com_github_bazelbuild_buildtools//edit:go_default_library
+# gazelle:map_kind bzl_library bzl_library @bazel_lib//:bzl_library.bzl
 gazelle(
     name = "gazelle",
     args = [
@@ -93,12 +94,4 @@ bzl_library(
     deps = ["@bazeldnf//bazeldnf:defs"],
 )
 
-bzl_library(
-    name = "deps",
-    srcs = ["deps.bzl"],
-    visibility = ["//visibility:public"],
-    deps = [
-        "@bazeldnf//bazeldnf:defs",
-        "@bazeldnf//bazeldnf:deps",
-    ],
-)
+# gazelle:exclude deps.bzl

MODULE.bazel

@@ -20,6 +20,7 @@ register_toolchains("@bazeldnf_toolchains//:all")
 bazel_dep(name = "bazel_skylib", version = "1.9.0")
 bazel_dep(name = "platforms", version = "1.0.0")
 bazel_dep(name = "bazel_features", version = "1.41.0")
+bazel_dep(name = "bazel_lib", version = "3.2.0")
 
 # if someone wants to build the bazeldnf toolchain from sources needs this set of dependencies
 bazel_dep(name = "gazelle", version = "0.47.0")
@@ -94,6 +95,4 @@ bazel_dep(name = "bazel_skylib_gazelle_plugin", version = "1.9.0", dev_dependenc
 bazel_dep(name = "aspect_bazel_lib", version = "2.22.5", dev_dependency = True)
 bazel_dep(name = "buildifier_prebuilt", version = "8.2.1.2", dev_dependency = True)
 bazel_dep(name = "rules_pkg", version = "1.2.0", dev_dependency = True)
-bazel_dep(name = "stardoc", version = "0.8.1", dev_dependency = True)
-bazel_dep(name = "rules_java", version = "9.5.0", dev_dependency = True)
 bazel_dep(name = "rules_cc", version = "0.2.16", dev_dependency = True)

bazeldnf/BUILD.bazel

@@ -1,4 +1,4 @@
-load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+load("@bazel_lib//:bzl_library.bzl", "bzl_library")
 load("//bazeldnf/private:resolved_bazeldnf_toolchain.bzl", "resolved_bazeldnf_toolchain")
 
 # this directory contains the public API from bazeldnf, anything on this directory
@@ -16,14 +16,8 @@ resolved_bazeldnf_toolchain(
     visibility = ["//visibility:public"],
 )
 
-bzl_library(
-    name = "alias_macros",
-    srcs = ["alias_macros.bzl"],
-    visibility = ["//visibility:public"],
-    deps = [
-        "//internal:rpm",
-    ],
-)
+# gazelle:exclude deps.bzl
+# gazelle:exclude alias_macros.bzl
 
 bzl_library(
     name = "defs",
@@ -37,13 +31,6 @@ bzl_library(
     ],
 )
 
-bzl_library(
-    name = "deps",
-    srcs = ["deps.bzl"],
-    visibility = ["//visibility:public"],
-    deps = [":repositories"],
-)
-
 bzl_library(
     name = "extensions",
     srcs = ["extensions.bzl"],
@@ -55,6 +42,14 @@ bzl_library(
     ],
 )
 
+exports_files(
+    [
+        "defs.bzl",
+        "deps.bzl",
+    ],
+    visibility = ["//:__subpackages__"],
+)
+
 bzl_library(
     name = "repositories",
     srcs = ["repositories.bzl"],
@@ -64,19 +59,12 @@ bzl_library(
         "//bazeldnf/private:toolchains_repo",
         "//tools:integrity",
         "//tools:version",
+        "@bazel_tools//tools/build_defs/repo:cache.bzl",  # keep
         "@bazel_tools//tools/build_defs/repo:http.bzl",
         "@bazel_tools//tools/build_defs/repo:utils.bzl",
     ],
 )
 
-exports_files(
-    [
-        "defs.bzl",
-        "deps.bzl",
-    ],
-    visibility = ["//:__subpackages__"],
-)
-
 bzl_library(
     name = "platforms",
     srcs = ["platforms.bzl"],

bazeldnf/extensions.bzl

@@ -6,7 +6,6 @@ based on: https://github.com/bazel-contrib/rules-template/blob/0dadcb716f06f6728
 """
 
 load("@bazel_features//:features.bzl", "bazel_features")
-load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_jar")
 load("//internal:rpm.bzl", rpm_repository = "rpm")
 load(":repositories.bzl", "bazeldnf_register_toolchains")
 

bazeldnf/private/BUILD.bazel

@@ -1,4 +1,4 @@
-load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+load("@bazel_lib//:bzl_library.bzl", "bzl_library")
 
 bzl_library(
     name = "toolchains_repo",

bazeldnf/repositories.bzl

@@ -38,6 +38,12 @@ def bazeldnf_dependencies():
         ],
         sha256 = "218efe8ee736d26a3572663b374a253c012b716d8af0c07e842e82f238a0a7ee",
     )
+    http_archive(
+        name = "bazel_lib",
+        sha256 = "e733937de2f542436c5d3d618e22c638489b40dfd251284050357babe71103d7",
+        strip_prefix = "bazel-lib-3.2.0",
+        url = "https://github.com/bazel-contrib/bazel-lib/releases/download/v3.2.0/bazel-lib-v3.2.0.tar.gz",
+    )
 
 ########
 # Remaining content of the file is only used to support toolchains.
@@ -77,7 +83,9 @@ def bazeldnf_register_toolchains(name, register = True, **kwargs):
     - TODO: create a convenience repository for the host platform like "bazeldnf_host"
     - create a repository exposing toolchains for each platform like "bazeldnf_platforms"
     - register a toolchain pointing at each platform
+
     Users can avoid this macro and do these steps themselves, if they want more control.
+
     Args:
         name: base name for all created repos, like "bazeldnf1_14"
         register: whether to call through to native.register_toolchains.

docs/BUILD.bazel

@@ -1,4 +1,4 @@
-load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+load("@bazel_lib//:bzl_library.bzl", "bzl_library")
 
 exports_files(["runner.bash.template"])
 
@@ -7,6 +7,7 @@ bzl_library(
     srcs = ["bazeldnf.bzl"],
     visibility = ["//:__subpackages__"],
     deps = [
+        "//bazeldnf:toolchain",
         "@bazel_skylib//lib:shell",
     ],
 )
@@ -23,6 +24,7 @@ bzl_library(
     srcs = ["rpmtree.bzl"],
     visibility = ["//:__subpackages__"],
     deps = [
+        ":rpm",
         "//bazeldnf:toolchain",
         "@bazel_skylib//lib:paths",
     ],

internal/BUILD.bazel

@@ -1,4 +1,4 @@
-load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+load("@bazel_lib//:bzl_library.bzl", "bzl_library")
 
 bzl_library(
     name = "integrity",