docs: move dependency management into respective bzl packages (#1459)

This moves the dependency management of what transitive files are needed
to generate docs for a .bzl file out of the docs directory and into the
respective bzl file's directory. This ensures that the bzl_library
targets we expose to users contain all the necessary dependencies.

Because there are some projects using the bzl_library targets in //docs,
some compatiblity aliases are added to make their migration path easier.
Those targets only public for historical reasons and shouldn't be used.

Work towards #1458

Author: rickeylev

BUILD.bazel

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 load(":version.bzl", "BAZEL_VERSION")
 
 package(default_visibility = ["//visibility:public"])
@@ -44,6 +45,12 @@ filegroup(
     ],
 )
 
+bzl_library(
+    name = "version_bzl",
+    srcs = ["version.bzl"],
+    visibility = ["//:__subpackages__"],
+)
+
 # Reexport of all bzl files used to allow downstream rules to generate docs
 # without shipping with a dependency on Skylib
 filegroup(

docs/BUILD.bazel

@@ -18,6 +18,8 @@ load("@bazel_skylib//rules:write_file.bzl", "write_file")
 load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
 load("//python/private:bzlmod_enabled.bzl", "BZLMOD_ENABLED")  # buildifier: disable=bzl-visibility
 
+# NOTE: Only public visibility for historical reasons.
+# This package is only for rules_python to generate its own docs.
 package(default_visibility = ["//visibility:public"])
 
 licenses(["notice"])  # Apache 2.0
@@ -32,47 +34,35 @@ _DOCS = {
     "python": "//docs:core-docs",
 }
 
-# We define these bzl_library targets here rather than in the //python package
-# because they're only used for doc generation. This way, we avoid requiring
-# our users to depend on Skylib.
-
-bzl_library(
-    name = "bazel_repo_tools",
-    srcs = [
-        "@bazel_tools//tools:bzl_srcs",
-    ],
+# Temporary compatibility aliases for some other projects depending on the old
+# bzl_library targets.
+alias(
+    name = "defs",
+    actual = "//python:defs_bzl",
+    deprecation = "Use //python:defs_bzl instead; targets under //docs are internal.",
 )
 
-bzl_library(
-    name = "defs",
-    srcs = [
-        "//python:defs.bzl",
-        "//python/private:reexports.bzl",
-    ],
-    deps = [
-        ":bazel_repo_tools",
-        "//python:defs_bzl",
-        "//python/private:reexports_bzl",
-    ],
+alias(
+    name = "bazel_repo_tools",
+    actual = "//python/private:bazel_tools_bzl",
+    deprecation = "Use @bazel_tools//tools:bzl_srcs instead; targets under //docs are internal.",
 )
 
 bzl_library(
     name = "pip_install_bzl",
-    srcs = [
-        "//python:bzl",
-        "//python/pip_install:bzl",
-    ],
+    deprecation = "Use //python:pip_bzl or //python/pip_install:pip_repository_bzl instead; " +
+                  "targets under //docs are internal.",
     deps = [
-        ":defs",
-        "//:version.bzl",
+        "//python:pip_bzl",
+        "//python/pip_install:pip_repository_bzl",
     ],
 )
 
-bzl_library(
+alias(
     name = "requirements_parser_bzl",
-    srcs = [
-        "//python/pip_install:requirements_parser.bzl",
-    ],
+    actual = "//python/pip_install:pip_repository_bzl",
+    deprecation = "Use //python/pip_install:pip_repository_bzl instead; Both the requirements " +
+                  "parser and targets under //docs are internal",
 )
 
 # Empty list means "compatible with all".
@@ -93,7 +83,9 @@ stardoc(
     out = "python.md_",
     input = "//python:defs.bzl",
     target_compatible_with = _TARGET_COMPATIBLE_WITH,
-    deps = [":defs"],
+    deps = [
+        "//python:defs_bzl",
+    ],
 )
 
 stardoc(
@@ -102,9 +94,7 @@ stardoc(
     input = "//python:pip.bzl",
     target_compatible_with = _TARGET_COMPATIBLE_WITH,
     deps = [
-        ":bazel_repo_tools",
-        ":pip_install_bzl",
-        "@bazel_skylib//lib:versions",
+        "//python:pip_bzl",
     ],
 )
 
@@ -114,10 +104,7 @@ stardoc(
     input = "//python/pip_install:pip_repository.bzl",
     target_compatible_with = _TARGET_COMPATIBLE_WITH,
     deps = [
-        ":bazel_repo_tools",
-        ":pip_install_bzl",
-        ":requirements_parser_bzl",
-        "@bazel_skylib//lib:versions",
+        "//python/pip_install:pip_repository_bzl",
     ],
 )
 

python/BUILD.bazel

@@ -82,6 +82,19 @@ bzl_library(
     ],
 )
 
+bzl_library(
+    name = "pip_bzl",
+    srcs = ["pip.bzl"],
+    deps = [
+        "//python/pip_install:pip_repository_bzl",
+        "//python/pip_install:repositories_bzl",
+        "//python/pip_install:requirements_bzl",
+        "//python/private:bzlmod_enabled_bzl",
+        "//python/private:full_version_bzl",
+        "//python/private:render_pkg_aliases_bzl",
+    ],
+)
+
 bzl_library(
     name = "proto_bzl",
     srcs = [
@@ -174,6 +187,27 @@ bzl_library(
     ],
 )
 
+bzl_library(
+    name = "repositories_bzl",
+    srcs = ["repositories.bzl"],
+    deps = [
+        ":versions_bzl",
+        "//python/private:bazel_tools_bzl",
+        "//python/private:bzlmod_enabled_bzl",
+        "//python/private:coverage_deps_bzl",
+        "//python/private:full_version_bzl",
+        "//python/private:internal_config_repo_bzl",
+        "//python/private:toolchains_repo_bzl",
+        "//python/private:which_bzl",
+    ],
+)
+
+bzl_library(
+    name = "versions_bzl",
+    srcs = ["versions.bzl"],
+    visibility = ["//:__subpackages__"],
+)
+
 # NOTE: Remember to add bzl_library targets to //tests:bzl_libraries
 # ========= bzl_library targets end =========
 

python/pip_install/BUILD.bazel

@@ -1,3 +1,70 @@
+# Copyright 2023 The Bazel Authors. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+
+package(
+    default_visibility = ["//:__subpackages__"],
+)
+
+bzl_library(
+    name = "pip_repository_bzl",
+    srcs = ["pip_repository.bzl"],
+    # Semi-public: What is intended to be public and what is intended to be
+    # internal is unclear. Some symbols are clearly public (e.g.
+    # package_annotations), some are clearly internal (e.g.
+    # pip_hub_repository_bzlmod), and many are unknown.
+    visibility = ["//visibility:public"],
+    deps = [
+        ":repositories_bzl",
+        ":requirements_parser_bzl",
+        "//python:repositories_bzl",
+        "//python:versions_bzl",
+        "//python/pip_install/private:generate_whl_library_build_bazel_bzl",
+        "//python/pip_install/private:srcs_bzl",
+        "//python/private:bzlmod_enabled_bzl",
+        "//python/private:normalize_name_bzl",
+        "//python/private:render_pkg_aliases_bzl",
+        "//python/private:toolchains_repo_bzl",
+        "//python/private:which_bzl",
+    ],
+)
+
+bzl_library(
+    name = "requirements_bzl",
+    srcs = ["requirements.bzl"],
+    deps = [
+        ":repositories_bzl",
+        "//python:defs_bzl",
+    ],
+)
+
+bzl_library(
+    name = "requirements_parser_bzl",
+    srcs = ["requirements_parser.bzl"],
+)
+
+bzl_library(
+    name = "repositories_bzl",
+    srcs = ["repositories.bzl"],
+    deps = [
+        "//:version_bzl",
+        "//python/private:bazel_tools_bzl",
+        "@bazel_skylib//lib:versions",
+    ],
+)
+
 filegroup(
     name = "distribution",
     srcs = glob(["*.bzl"]) + [

python/pip_install/private/BUILD.bazel

@@ -1,3 +1,4 @@
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 load(":pip_install_utils.bzl", "srcs_module")
 
 package(default_visibility = ["//:__subpackages__"])
@@ -22,3 +23,16 @@ srcs_module(
     srcs = "//python/pip_install:py_srcs",
     dest = ":srcs.bzl",
 )
+
+bzl_library(
+    name = "generate_whl_library_build_bazel_bzl",
+    srcs = ["generate_whl_library_build_bazel.bzl"],
+    deps = [
+        "//python/private:normalize_name_bzl",
+    ],
+)
+
+bzl_library(
+    name = "srcs_bzl",
+    srcs = ["srcs.bzl"],
+)

python/private/BUILD.bazel

@@ -18,6 +18,10 @@ load("//python:py_library.bzl", "py_library")
 load("//python:versions.bzl", "print_toolchains_checksums")
 load(":stamp.bzl", "stamp_build_setting")
 
+package(
+    default_visibility = ["//:__subpackages__"],
+)
+
 licenses(["notice"])
 
 filegroup(
@@ -53,13 +57,34 @@ bzl_library(
 )
 
 bzl_library(
-    name = "util_bzl",
-    srcs = ["util.bzl"],
-    visibility = [
-        "//docs:__subpackages__",
-        "//python:__subpackages__",
+    name = "bzlmod_enabled_bzl",
+    srcs = ["bzlmod_enabled.bzl"],
+)
+
+bzl_library(
+    name = "coverage_deps_bzl",
+    srcs = ["coverage_deps.bzl"],
+    deps = [
+        ":bazel_tools_bzl",
+        ":version_label_bzl",
     ],
-    deps = ["@bazel_skylib//lib:types"],
+)
+
+bzl_library(
+    name = "full_version_bzl",
+    srcs = ["full_version.bzl"],
+    deps = ["//python:versions_bzl"],
+)
+
+bzl_library(
+    name = "internal_config_repo_bzl",
+    srcs = ["internal_config_repo.bzl"],
+    deps = [":bzlmod_enabled_bzl"],
+)
+
+bzl_library(
+    name = "normalize_name_bzl",
+    srcs = ["normalize_name.bzl"],
 )
 
 bzl_library(
@@ -138,12 +163,51 @@ bzl_library(
     deps = [":bazel_tools_bzl"],
 )
 
+bzl_library(
+    name = "render_pkg_aliases_bzl",
+    srcs = ["render_pkg_aliases.bzl"],
+    deps = [
+        ":normalize_name_bzl",
+        ":text_util_bzl",
+        ":version_label_bzl",
+    ],
+)
+
 bzl_library(
     name = "stamp_bzl",
     srcs = ["stamp.bzl"],
     visibility = ["//:__subpackages__"],
 )
 
+bzl_library(
+    name = "text_util_bzl",
+    srcs = ["text_util.bzl"],
+)
+
+bzl_library(
+    name = "toolchains_repo_bzl",
+    srcs = ["toolchains_repo.bzl"],
+    deps = [
+        ":which_bzl",
+        "//python:versions_bzl",
+    ],
+)
+
+bzl_library(
+    name = "util_bzl",
+    srcs = ["util.bzl"],
+    visibility = [
+        "//docs:__subpackages__",
+        "//python:__subpackages__",
+    ],
+    deps = ["@bazel_skylib//lib:types"],
+)
+
+bzl_library(
+    name = "version_label_bzl",
+    srcs = ["version_label.bzl"],
+)
+
 bzl_library(
     name = "which_bzl",
     srcs = ["which.bzl"],
@@ -162,7 +226,6 @@ bzl_library(
         # sources.
         "@bazel_tools//tools:bzl_srcs",
     ],
-    visibility = ["//python:__pkg__"],
 )
 
 # Needed to define bzl_library targets for docgen. (We don't define the