Docgen: Split the "global functions" page into multiple ones

======

- Primary motivation: #16383
- Currently, the pages generated by docgen is a `PageTitle -> Page` map. It's then separated into multiple categories based on the `docCategory` value of the `@StarlarkBuiltin` annotation, with the exception of the "global functions" page, which is special-cased.
  - This has several issues: for one, the configuration fragment named "proto" has a conflict with the top-level module named "proto", since everything is in the same map (we work around this by naming the latter "ProtoModule", which is wrong and confusing).
  - For another, we can't easily split the "global functions" page into multiple ones, unless we special-case every one of them.
- So we structure the returned pages into a `Category -> [Page]` map. The new category `GLOBAL_FUNCTION` contains a few pages, each of which contains global functions available in a certain environment (see d1c72d7). The other categories are largely unchanged.
- We also change the URL format of these pages from `..../lib/$TITLE.html` to `..../lib/$CATEGORY/$TITLE.html`.
  - The bulk of this CL involves fixing up all links.
  - This also means that "proto" the configuration fragment and "proto" the top-level module can now both be named "proto".
  - This does break old links, but I can't find the energy to set up redirects for everything...
- Miscellaneous changes:
  - The `starlark-nav.vm` page is removed; nobody uses it.
  - Renamed the category overview pages from `..../lib/starlark-$CATEGORY.html` to just `..../lib/$CATEGORY.html`, now that there's no pages directly under `..../lib`.
  - A bunch of small documentation fixes across the codebase as I went through them.

Fixes #16383

PiperOrigin-RevId: 523745069
Change-Id: Idfbb29f1f589bde58ac5a8b199a788245286256a

site/en/concepts/platforms.md

@@ -418,7 +418,7 @@ contact [bazel-dev]{: .external}.
 [Platforms examples]: https://github.com/hlopko/bazel_platforms_examples
 [platform mappings design]: https://docs.google.com/document/d/1Vg_tPgiZbSrvXcJ403vZVAGlsWhH9BUDrAxMOYnO0Ls/edit
 [platform Rule]: /reference/be/platform#platform
-[register_toolchains Function]: /rules/lib/globals#register_toolchains
+[register_toolchains Function]: /rules/lib/globals/workspace#register_toolchains
 [Rust rules]: https://github.com/bazelbuild/rules_rust
 [select()]: /docs/configurable-attributes
 [select() Platforms]: /docs/configurable-attributes#platforms

site/en/concepts/visibility.md

@@ -275,7 +275,7 @@ Load visibility is available as of Bazel 6.0.
 ### Declaring load visibility {:#declaring-load-visibility}
 
 To set the load visibility of a `.bzl` file, call the
-[`visibility()`](/rules/lib/globals#visibility) function from within the file.
+[`visibility()`](/rules/lib/globals/bzl#visibility) function from within the file.
 The argument to `visibility()` is a list of package specifications, just like
 the [`packages`](/reference/be/functions#package_group.packages) attribute of
 `package_group`. However, `visibility()` does not accept negative package

site/en/configure/integrate-cpp.md

@@ -17,14 +17,14 @@ should use the helper function available at
 [@bazel_tools//tools/cpp:toolchain_utils.bzl](https://source.bazel.build/bazel/+/main:tools/cpp/toolchain_utils.bzl;l=23),
 which works both when toolchains are disabled and enabled. To depend on a C++
 toolchain in your rule, add a
-[`Label`](/rules/lib/attr#label)
+[`Label`](/rules/lib/toplevel/attr#label)
 attribute named `_cc_toolchain` and point it
 to `@bazel_tools//tools/cpp:current_cc_toolchain` (an instance of
 `cc_toolchain_alias` rule, that points to the currently selected C++ toolchain).
 Then, in the rule implementation, use
 [`find_cpp_toolchain(ctx)`](https://source.bazel.build/bazel/+/main:tools/cpp/toolchain_utils.bzl;l=23)
 to get the
-[`CcToolchainInfo`](/rules/lib/CcToolchainInfo).
+[`CcToolchainInfo`](/rules/lib/providers/CcToolchainInfo).
 A complete working example can be found
 [in the rules_cc examples](https://github.com/bazelbuild/rules_cc/blob/main/examples/write_cc_toolchain_cpu/write_cc_toolchain_cpu.bzl){: .external}.
 
@@ -42,14 +42,14 @@ you need the following:
 
 * `features` and `action_configs` - these come from the `CcToolchainConfigInfo`
   and encapsulated in `CcToolchainInfo`
-* `FeatureConfiguration` - returned by [cc_common.configure_features](/rules/lib/cc_common#configure_features)
+* `FeatureConfiguration` - returned by [cc_common.configure_features](/rules/lib/toplevel/cc_common#configure_features)
 * cc toolchain config variables - returned by
-  [cc_common.create_compile_variables](/rules/lib/cc_common#create_compile_variables)
+  [cc_common.create_compile_variables](/rules/lib/toplevel/cc_common#create_compile_variables)
   or
-  [cc_common.create_link_variables](/rules/lib/cc_common#create_link_variables).
+  [cc_common.create_link_variables](/rules/lib/toplevel/cc_common#create_link_variables).
 
 There still are tool-specific getters, such as
-[compiler_executable](/rules/lib/CcToolchainInfo#compiler_executable).
+[compiler_executable](/rules/lib/providers/CcToolchainInfo#compiler_executable).
 Prefer `get_tool_for_action` over these, as tool-specific getters will
 eventually be removed.
 
@@ -59,10 +59,10 @@ A complete working example can be found
 ## Implementing Starlark rules that depend on C++ rules and/or that C++ rules can depend on {:#implement-starlark-rules}
 
 Most C++ rules provide
-[`CcInfo`](/rules/lib/CcInfo),
-a provider containing [`CompilationContext`](/rules/lib/CompilationContext)
+[`CcInfo`](/rules/lib/providers/CcInfo),
+a provider containing [`CompilationContext`](/rules/lib/builtins/CompilationContext)
 and
-[`LinkingContext`](/rules/lib/LinkingContext).
+[`LinkingContext`](/rules/lib/builtins/LinkingContext).
 Through these it is possible to access information such as all transitive headers
 or libraries to link. From `CcInfo` and from the `CcToolchainInfo` custom
 Starlark rules should be able to get all the information they need.

site/en/docs/bazel-and-apple.md

@@ -36,20 +36,20 @@ when building your macOS and iOS projects:
 
 *  Modules:
 
-   *  [`apple_bitcode_mode`](/rules/lib/apple_bitcode_mode)
-   *  [`apple_common`](/rules/lib/apple_common)
-   *  [`apple_platform`](/rules/lib/apple_platform)
-   *  [`apple_platform_type`](/rules/lib/apple_platform_type)
-   *  [`apple_toolchain`](/rules/lib/apple_toolchain)
-   *  [`XcodeVersionConfig`](/rules/lib/XcodeVersionConfig)
+   *  [`apple_bitcode_mode`](/rules/lib/builtins/apple_bitcode_mode)
+   *  [`apple_common`](/rules/lib/toplevel/apple_common)
+   *  [`apple_platform`](/rules/lib/builtins/apple_platform)
+   *  [`apple_platform_type`](/rules/lib/builtins/apple_platform_type)
+   *  [`apple_toolchain`](/rules/lib/builtins/apple_toolchain)
 
 *  Configuration fragments:
 
-   *  [`apple`](/rules/lib/apple)
+   *  [`apple`](/rules/lib/fragments/apple)
 
 *  Providers:
 
-   *  [`ObjcProvider`](/rules/lib/ObjcProvider)
+   *  [`ObjcProvider`](/rules/lib/providers/ObjcProvider)
+   *  [`XcodeVersionConfig`](/rules/lib/providers/XcodeVersionConfig)
 
 ## Xcode selection {:#xcode-selection}
 
@@ -61,7 +61,7 @@ the set of available Xcode versions and sets a default version if
 represented in the `--xcode_config` target.
 
 If you do not pass `--xcode_config`, Bazel will use the autogenerated
-[`XcodeVersionConfig`](/rules/lib/XcodeVersionConfig) that represents the
+[`XcodeVersionConfig`](/rules/lib/providers/XcodeVersionConfig) that represents the
 Xcode versions available on your host machine. The default version is
 the newest available Xcode version. This is appropriate for local execution.
 

site/en/docs/bazel-and-java.md

@@ -131,17 +131,17 @@ The following modules, configuration fragments, and providers will help you
 [extend Bazel's capabilities](/extending/concepts) when building your Java
 projects:
 
-*   Main Java provider: [`java_common`](/rules/lib/java_common)
-*   Main Java module: [`JavaInfo`](/rules/lib/JavaInfo)
-*   Configuration fragment: [`java`](/rules/lib/java)
+*   Main Java module: [`java_common`](/rules/lib/toplevel/java_common)
+*   Main Java provider: [`JavaInfo`](/rules/lib/providers/JavaInfo)
+*   Configuration fragment: [`java`](/rules/lib/fragments/java)
 *   Other modules:
 
-    *   [`java_annotation_processing`](/rules/lib/java_annotation_processing)
-    *   [`java_compilation_info`](/rules/lib/java_compilation_info)
-    *   [`java_output`](/rules/lib/java_output)
-    *   [`java_output_jars`](/rules/lib/java_output_jars)
-    *   [`JavaRuntimeInfo`](/rules/lib/JavaRuntimeInfo)
-    *   [`JavaToolchainInfo`](/rules/lib/JavaToolchainInfo)
+    *   [`java_annotation_processing`](/rules/lib/builtins/java_annotation_processing)
+    *   [`java_compilation_info`](/rules/lib/providers/java_compilation_info)
+    *   [`java_output`](/rules/lib/builtins/java_output)
+    *   [`java_output_jars`](/rules/lib/providers/java_output_jars)
+    *   [`JavaRuntimeInfo`](/rules/lib/providers/JavaRuntimeInfo)
+    *   [`JavaToolchainInfo`](/rules/lib/providers/JavaToolchainInfo)
 
 ## Configuring the Java toolchains {:#config-java-toolchains}
 

site/en/docs/cc-toolchain-config-reference.md

@@ -28,14 +28,14 @@ Bazel needs to know the following:
 If the compiler has support for multiple architectures, Bazel needs to configure
 them separately.
 
-[`CcToolchainConfigInfo`](/rules/lib/CcToolchainConfigInfo) is a provider that provides the necessary level of
+[`CcToolchainConfigInfo`](/rules/lib/providers/CcToolchainConfigInfo) is a provider that provides the necessary level of
 granularity for configuring the behavior of Bazel's C++ rules. By default,
 Bazel automatically configures `CcToolchainConfigInfo` for your build, but you
 have the option to configure it manually. For that, you need a Starlark rule
 that provides the `CcToolchainConfigInfo` and you need to point the
 [`toolchain_config`](/reference/be/c-cpp#cc_toolchain.toolchain_config) attribute of the `cc_toolchain` to your rule.
 You can create the `CcToolchainConfigInfo` by calling
-[`cc_common.create_cc_toolchain_config_info()`](/rules/lib/cc_common#create_cc_toolchain_config_info).
+[`cc_common.create_cc_toolchain_config_info()`](/rules/lib/toplevel/cc_common#create_cc_toolchain_config_info).
 You can find Starlark constructors for all structs you'll need in the process in
 [`@rules_cc//cc:cc_toolchain_config_lib.bzl`](https://github.com/bazelbuild/rules_cc/blob/master/cc/cc_toolchain_config_lib.bzl){: .external}.
 

site/en/docs/user-manual.md

@@ -1325,7 +1325,7 @@ The label of a platform rule that describes the host system.
 The platforms that are available as execution platforms to run actions.
 Platforms can be specified by exact target, or as a target pattern. These
 platforms will be considered before those declared in the WORKSPACE file by
-[register_execution_platforms()](/rules/lib/globals#register_execution_platforms).
+[register_execution_platforms()](/rules/lib/globals/workspace#register_execution_platforms).
 This option accepts a comma-separated list of platforms in order of priority.
 If the flag is passed multiple times, the most recent overrides.
 
@@ -1334,7 +1334,7 @@ If the flag is passed multiple times, the most recent overrides.
 The toolchain rules to be considered during toolchain resolution. Toolchains
 can be specified by exact target, or as a target pattern. These toolchains will
 be considered before those declared in the WORKSPACE file by
-[register_toolchains()](/rules/lib/globals#register_toolchains).
+[register_toolchains()](/rules/lib/globals/workspace#register_toolchains).
 
 #### `--toolchain_resolution_debug={{ "<var>" }}regex{{ "</var>" }}` {:#toolchain-resolution-debug}
 

site/en/extending/aspects.md

@@ -6,7 +6,7 @@ Book: /_book.yaml
 {% include "_buttons.html" %}
 
 This page explains the basics and benefits of using
-[aspects](/rules/lib/globals#aspect) and provides simple and advanced
+[aspects](/rules/lib/globals/bzl#aspect) and provides simple and advanced
 examples.
 
 Aspects allow augmenting build dependency graphs with additional information
@@ -111,7 +111,7 @@ print_aspect = aspect(
 )
 ```
 Aspect definitions are similar to rule definitions, and defined using
-the [`aspect`](/rules/lib/globals#aspect) function.
+the [`aspect`](/rules/lib/globals/bzl#aspect) function.
 
 Just like a rule, an aspect has an implementation function which in this case is
 ``_print_aspect_impl``.
@@ -141,12 +141,12 @@ Aspect implementation functions are similar to the rule implementation
 functions. They return [providers](/extending/rules#providers), can generate
 [actions](/extending/rules#actions), and take two arguments:
 
-*  `target`: the [target](/rules/lib/Target) the aspect is being applied to.
-*   `ctx`: [`ctx`](/rules/lib/ctx) object that can be used to access attributes
+*  `target`: the [target](/rules/lib/builtins/Target) the aspect is being applied to.
+*   `ctx`: [`ctx`](/rules/lib/builtins/ctx) object that can be used to access attributes
     and generate outputs and actions.
 
 The implementation function can access the attributes of the target rule via
-[`ctx.rule.attr`](/rules/lib/ctx#rule). It can examine providers that are
+[`ctx.rule.attr`](/rules/lib/builtins/ctx#rule). It can examine providers that are
 provided by the target to which it is applied (via the `target` argument).
 
 Aspects are required to return a list of providers. In this example, the aspect
@@ -329,12 +329,12 @@ implementation of aspect A. The providers that a rule implementation propagates
 are created and frozen before aspects are applied and cannot be modified from an
 aspect. It is an error if a target and an aspect that is applied to it each
 provide a provider with the same type, with the exceptions of
-[`OutputGroupInfo`](/rules/lib/OutputGroupInfo)
+[`OutputGroupInfo`](/rules/lib/providers/OutputGroupInfo)
 (which is merged, so long as the
 rule and aspect specify different output groups) and
-[`InstrumentedFilesInfo`](/rules/lib/InstrumentedFilesInfo)
+[`InstrumentedFilesInfo`](/rules/lib/providers/InstrumentedFilesInfo)
 (which is taken from the aspect). This means that aspect implementations may
-never return [`DefaultInfo`](/rules/lib/DefaultInfo).
+never return [`DefaultInfo`](/rules/lib/providers/DefaultInfo).
 
 The parameters and private attributes are passed in the attributes of the
 ``ctx``. This example references the ``extension`` parameter and determines
@@ -401,4 +401,4 @@ itself, and all of the targets accessible recursively via ``deps``.
 
 ## References
 
-* [`aspect` API reference](/rules/lib/globals#aspect)
+* [`aspect` API reference](/rules/lib/globals/bzl#aspect)

site/en/extending/concepts.md

@@ -83,7 +83,7 @@ they will not be executed.
 The two links below will be very useful when writing your own extensions. Keep
 them within reach:
 
-* The [API reference](/rules/lib/starlark-overview)
+* The [API reference](/rules/lib)
 
 * [Examples](https://github.com/bazelbuild/examples/tree/master/rules)
 

site/en/extending/config.md

@@ -14,7 +14,7 @@ This makes it possible to:
 *   define custom flags for your project, obsoleting the need for
      [`--define`](/docs/configurable-attributes#custom-keys)
 *   write
-    [transitions](/rules/lib/transition#transition) to configure deps in
+    [transitions](/rules/lib/builtins/transition#transition) to configure deps in
     different configurations than their parents
     (such as `--compilation_mode=opt` or `--cpu=arm`)
 *   bake better defaults into rules (such as automatically build `//my:android_app`
@@ -50,7 +50,7 @@ set via [user-defined transitions](#user-defined-transitions).
 
 Build settings are rules like any other rule and are differentiated using the
 Starlark `rule()` function's `build_setting`
-[attribute](/rules/lib/globals#rule.build_setting).
+[attribute](/rules/lib/globals/bzl#rule.build_setting).
 
 ```python
 # example/buildsettings/build_settings.bzl
@@ -63,13 +63,13 @@ string_flag = rule(
 The `build_setting` attribute takes a function that designates the type of the
 build setting. The type is limited to a set of basic Starlark types like
 `bool` and `string`. See the `config` module
-[documentation](/rules/lib/config)  for details. More complicated typing can be
+[documentation](/rules/lib/toplevel/config)  for details. More complicated typing can be
 done in the rule's implementation function. More on this below.
 
 The `config` module's functions takes an optional boolean parameter, `flag`,
 which is set to false by default. if `flag` is set to true, the build setting
 can be set on the command line by users as well as internally by rule writers
-via default values and [transitions](/rules/lib/transition#transition).
+via default values and [transitions](/rules/lib/builtins/transition#transition).
 Not all settings should be settable by users. For example, if you as a rule
 writer have some debug mode that you'd like to turn on inside test rules,
 you don't want to give users the ability to indiscriminately turn on that
@@ -80,7 +80,7 @@ feature inside other non-test rules.
 Like all rules, build setting rules have [implementation functions](/extending/rules#implementation-function).
 The basic Starlark-type value of the build settings can be accessed via the
 `ctx.build_setting_value` method. This method is only available to
-[`ctx`](/rules/lib/ctx) objects of build setting rules. These implementation
+[`ctx`](/rules/lib/builtins/ctx) objects of build setting rules. These implementation
 methods can directly forward the build settings value or do additional work on
 it, like type checking or more complex struct creation. Here's how you would
 implement an `enum`-typed build setting:
@@ -328,7 +328,7 @@ can't customely defined.
 Label-typed settings will eventually replace the functionality of late-bound
 defaults. Late-bound default attributes are Label-typed attributes whose
 final values can be affected by configuration. In Starlark, this will replace
-the [`configuration_field`](/rules/lib/globals#configuration_field)
+the [`configuration_field`](/rules/lib/globals/bzl#configuration_field)
  API.
 
 ```python
@@ -388,7 +388,7 @@ config_setting(
 ## User-defined transitions {:#user-defined-transitions}
 
 A configuration
-[transition](/rules/lib/transition#transition)
+[transition](/rules/lib/builtins/transition#transition)
 maps the transformation from one configured target to another within the
 build graph.
 
@@ -423,7 +423,7 @@ with special restrictions.
 
 In Starlark, transitions are defined much like rules, with a defining
 `transition()`
-[function](/rules/lib/transition#transition)
+[function](/rules/lib/builtins/transition#transition)
 and an implementation function.
 
 ```python

site/en/extending/depsets.md

@@ -5,7 +5,7 @@ Book: /_book.yaml
 
 {% include "_buttons.html" %}
 
-[Depsets](/rules/lib/depset) are a specialized data structure for efficiently
+[Depsets](/rules/lib/builtins/depset) are a specialized data structure for efficiently
 collecting data across a target’s transitive dependencies. They are an essential
 element of rule processing.
 
@@ -35,7 +35,7 @@ previous without having to read or copy them.
 Each node in the DAG holds a list of direct elements and a list of child nodes.
 The contents of the depset are the transitive elements, such as the direct elements
 of all the nodes. A new depset can be created using the
-[depset](/rules/lib/globals#depset) constructor: it accepts a list of direct
+[depset](/rules/lib/globals/bzl#depset) constructor: it accepts a list of direct
 elements and another list of child nodes.
 
 ```python
@@ -47,7 +47,7 @@ print(t)    # depset(["d", "e", "a", "b", "c"])
 ```
 
 To retrieve the contents of a depset, use the
-[to_list()](/rules/lib/depset#to_list) method. It returns a list of all transitive
+[to_list()](/rules/lib/builtins/depset#to_list) method. It returns a list of all transitive
 elements, not including duplicates. There is no way to directly inspect the
 precise structure of the DAG, although this structure does affect the order in
 which the elements are returned.
@@ -343,5 +343,5 @@ For more information about using depsets efficiently, see the [performance](/rul
 
 ## API Reference
 
-Please see [here](/rules/lib/depset) for more details.
+Please see [here](/rules/lib/builtins/depset) for more details.
 

site/en/extending/exec-groups.md

@@ -25,7 +25,7 @@ like linking in C++ builds without over-allocating to less demanding tasks.
 ## Defining execution groups {:#defining-exec-groups}
 
 During rule definition, rule authors can
-[declare](/rules/lib/globals#exec_group)
+[declare](/rules/lib/globals/bzl#exec_group)
 a set of execution groups. On each execution group, the rule author can specify
 everything needed to select an execution platform for that execution group,
 namely any constraints via `exec_compatible_with` and toolchain types via
@@ -52,9 +52,9 @@ my_rule = rule(
 
 In the code snippet above, you can see that tool dependencies can also specify
 transition for an exec group using the
-[`cfg`](/rules/lib/attr#label)
+[`cfg`](/rules/lib/toplevel/attr#label)
 attribute param and the
-[`config`](/rules/lib/config)
+[`config`](/rules/lib/toplevel/config)
 module. The module exposes an `exec` function which takes a single string
 parameter which is the name of the exec group for which the dependency should be
 built.
@@ -109,8 +109,8 @@ of:
 In the rule implementation, you can declare that actions should be run on the
 execution platform of an execution group. You can do this by using the `exec_group`
 param of action generating methods, specifically [`ctx.actions.run`]
-(/rules/lib/actions#run) and
-[`ctx.actions.run_shell`](/rules/lib/actions#run_shell).
+(/rules/lib/builtins/actions#run) and
+[`ctx.actions.run_shell`](/rules/lib/builtins/actions#run_shell).
 
 ```python
 # foo.bzl