fix xrefs, docs, expand docs

Author: rickeylev

docs/BUILD.bazel

@@ -100,6 +100,8 @@ sphinx_stardocs(
         "//python:py_test_bzl",
         "//python:repositories_bzl",
         "//python/api:api_bzl",
+        "//python/api:executables_bzl",
+        "//python/api:libraries_bzl",
         "//python/cc:py_cc_toolchain_bzl",
         "//python/cc:py_cc_toolchain_info_bzl",
         "//python/entry_points:py_console_script_binary_bzl",

docs/extending.md

@@ -31,15 +31,29 @@ for the development of APIs to support custom derived rules.
 Custom rules can be created using the core rules as a basis by using their rule
 builder APIs.
 
-* {bzl:obj}`//python/apis:executables.bzl%executables` for builders for executables
-* {bzl:obj}`//python/apis:libraries.bzl%libraries` for builders for libraries
+* [`//python/apis:executables.bzl`](#python-apis-executables-bzl): builders for
+  executables.
+* [`//python/apis:libraries.bzl`](#python-apis-libraries-bzl): builders for
+  libraries.
 
 These builders create {bzl:obj}`ruleb.Rule` objects, which are thin
 wrappers around the keyword arguments eventually passed to the `rule()`
 function. These builder APIs give access to the _entire_ rule definition and
 allow arbitrary modifications.
 
-### Example: validating a source file
+This is level of control is powerful, but also volatile. A rule definition
+contains many details that _must_ change as the implementation changes. What
+is more or less likely to change isn't known in advance, but some general
+rules are:
+
+* Additive behavior to public attributes will be less prone to breaking.
+* Internal attributes that directly support a public attribute are likely
+  reliable.
+* Internal attributes that support an action are more likely to change.
+* Rule toolchains are moderately stable (toolchains are mostly internal to
+  how a rule works, but custom toolchains are supported).
+
+## Example: validating a source file
 
 In this example, we derive from `py_library` a custom rule that verifies source
 code contains the word "snakes". It does this by:
@@ -95,7 +109,7 @@ def create_has_snakes_rule():
 has_snakes_library = create_has_snakes_rule()
 ```
 
-### Example: adding transitions
+## Example: adding transitions
 
 In this example, we derive from `py_binary` to force building for a particular
 platform. We do this by:

python/api/BUILD.bazel

@@ -25,6 +25,26 @@ bzl_library(
     deps = ["//python/private/api:api_bzl"],
 )
 
+bzl_library(
+    name = "executables_bzl",
+    srcs = ["executables.bzl"],
+    visibility = ["//visibility:public"],
+    deps = [
+        "//python/private:py_binary_rule_bzl",
+        "//python/private:py_executable_bzl",
+        "//python/private:py_test_rule_bzl",
+    ],
+)
+
+bzl_library(
+    name = "libraries_bzl",
+    srcs = ["libraries.bzl"],
+    visibility = ["//visibility:public"],
+    deps = [
+        "//python/private:py_library_bzl",
+    ],
+)
+
 filegroup(
     name = "distribution",
     srcs = glob(["**"]),

python/api/executables.bzl

@@ -12,18 +12,20 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Loading-phase APIs specific to executables (binaries/tests).
+"""
+{#python-apis-executables-bzl}
+Loading-phase APIs specific to executables (binaries/tests).
 
 :::{versionadded} VERSION_NEXT_FEATURE
 :::
 """
 
 load("//python/private:py_binary_rule.bzl", "create_py_binary_rule_builder")
 load("//python/private:py_executable.bzl", "create_executable_rule_builder")
-load("//python/private:py_test_rule.bzl", "create_test_rule_builder")
+load("//python/private:py_test_rule.bzl", "create_py_test_rule_builder")
 
 executables = struct(
     py_binary_rule_builder = create_py_binary_rule_builder,
-    py_test_rule_builder = create_test_rule_builder,
+    py_test_rule_builder = create_py_test_rule_builder,
     executable_rule_builder = create_executable_rule_builder,
 )

python/api/libraries.bzl

@@ -12,7 +12,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Loading-phase APIs specific to executables (binaries/tests).
+"""
+{#python-apis-libraries-bzl}
+Loading-phase APIs specific to executables (binaries/tests).
 
 :::{versionadded} VERSION_NEXT_FEATURE
 :::

python/private/BUILD.bazel

@@ -427,6 +427,7 @@ bzl_library(
         ":attributes_bzl",
         ":common_bzl",
         ":flags_bzl",
+        ":precompile_bzl",
         ":py_cc_link_params_info_bzl",
         ":py_internal_bzl",
         ":rule_builders_bzl",
@@ -446,8 +447,6 @@ bzl_library(
     name = "py_library_rule_bzl",
     srcs = ["py_library_rule.bzl"],
     deps = [
-        ":common_bzl",
-        ":precompile_bzl",
         ":py_library_bzl",
     ],
 )

python/private/py_test_rule.bzl

@@ -42,7 +42,7 @@ def create_py_test_rule_builder():
 
     Returns:
         {type}`ruleb.Rule` with the necessary settings
-        for creating a `py_binary` rule.
+        for creating a `py_test` rule.
     """
     builder = create_executable_rule_builder(
         implementation = _py_test_impl,