Docgen: Split the "global functions" page into multiple ones
======
- Primary motivation: https://github.com/bazelbuild/bazel/issues/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 https://github.com/bazelbuild/bazel/commit/d1c72d70f45c2362a87d22ebac9e5bb7f2b4ae0a). 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 https://github.com/bazelbuild/bazel/issues/16383
PiperOrigin-RevId: 523745069
Change-Id: Idfbb29f1f589bde58ac5a8b199a788245286256a
diff --git a/site/en/concepts/platforms.md b/site/en/concepts/platforms.md
index 6db8608..57fc150 100644
--- a/site/en/concepts/platforms.md
+++ b/site/en/concepts/platforms.md
@@ -418,7 +418,7 @@
[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
diff --git a/site/en/concepts/visibility.md b/site/en/concepts/visibility.md
index e13f5ea..dab44fd 100644
--- a/site/en/concepts/visibility.md
+++ b/site/en/concepts/visibility.md
@@ -275,7 +275,7 @@
### 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
diff --git a/site/en/configure/integrate-cpp.md b/site/en/configure/integrate-cpp.md
index 7f1c84e..8a01fd3 100644
--- a/site/en/configure/integrate-cpp.md
+++ b/site/en/configure/integrate-cpp.md
@@ -17,14 +17,14 @@
[@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 @@
* `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 @@
## 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.
diff --git a/site/en/docs/bazel-and-apple.md b/site/en/docs/bazel-and-apple.md
index 3c750fd..443c6c9 100644
--- a/site/en/docs/bazel-and-apple.md
+++ b/site/en/docs/bazel-and-apple.md
@@ -36,20 +36,20 @@
* 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 @@
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.
diff --git a/site/en/docs/bazel-and-java.md b/site/en/docs/bazel-and-java.md
index 9a9132d..ea8a11b 100644
--- a/site/en/docs/bazel-and-java.md
+++ b/site/en/docs/bazel-and-java.md
@@ -131,17 +131,17 @@
[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}
diff --git a/site/en/docs/cc-toolchain-config-reference.md b/site/en/docs/cc-toolchain-config-reference.md
index be0be10..c7e3854 100644
--- a/site/en/docs/cc-toolchain-config-reference.md
+++ b/site/en/docs/cc-toolchain-config-reference.md
@@ -28,14 +28,14 @@
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}.
diff --git a/site/en/docs/user-manual.md b/site/en/docs/user-manual.md
index 75aa2d9..b593b82 100644
--- a/site/en/docs/user-manual.md
+++ b/site/en/docs/user-manual.md
@@ -1325,7 +1325,7 @@
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 @@
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}
diff --git a/site/en/extending/aspects.md b/site/en/extending/aspects.md
index ecd89d2..e825757 100644
--- a/site/en/extending/aspects.md
+++ b/site/en/extending/aspects.md
@@ -6,7 +6,7 @@
{% 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 @@
)
```
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 @@
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 @@
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 @@
## References
-* [`aspect` API reference](/rules/lib/globals#aspect)
+* [`aspect` API reference](/rules/lib/globals/bzl#aspect)
diff --git a/site/en/extending/concepts.md b/site/en/extending/concepts.md
index e71d365..e03e7db 100644
--- a/site/en/extending/concepts.md
+++ b/site/en/extending/concepts.md
@@ -83,7 +83,7 @@
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)
diff --git a/site/en/extending/config.md b/site/en/extending/config.md
index 1288c6c..1b4dbb3 100644
--- a/site/en/extending/config.md
+++ b/site/en/extending/config.md
@@ -14,7 +14,7 @@
* 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 @@
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 @@
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 @@
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 @@
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 @@
## 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 @@
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
diff --git a/site/en/extending/depsets.md b/site/en/extending/depsets.md
index d69f1c3..07f00f4 100644
--- a/site/en/extending/depsets.md
+++ b/site/en/extending/depsets.md
@@ -5,7 +5,7 @@
{% 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 @@
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 @@
```
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 @@
## API Reference
-Please see [here](/rules/lib/depset) for more details.
+Please see [here](/rules/lib/builtins/depset) for more details.
diff --git a/site/en/extending/exec-groups.md b/site/en/extending/exec-groups.md
index 9abdf1d..80492e1 100644
--- a/site/en/extending/exec-groups.md
+++ b/site/en/extending/exec-groups.md
@@ -25,7 +25,7 @@
## 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 @@
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 @@
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
diff --git a/site/en/extending/macros.md b/site/en/extending/macros.md
index 356383e..a6ba77c 100644
--- a/site/en/extending/macros.md
+++ b/site/en/extending/macros.md
@@ -125,7 +125,7 @@
## Instantiating native rules {:#instantiating-native-rules}
Native rules (rules that don't need a `load()` statement) can be
-instantiated from the [native](/rules/lib/native) module:
+instantiated from the [native](/rules/lib/toplevel/native) module:
```python
def my_macro(name, visibility=None):
@@ -137,7 +137,7 @@
```
If you need to know the package name (for example, which `BUILD` file is calling the
-macro), use the function [native.package_name()](/rules/lib/native#package_name).
+macro), use the function [native.package_name()](/rules/lib/toplevel/native#package_name).
Note that `native` can only be used in `.bzl` files, and not in `WORKSPACE` or
`BUILD` files.
@@ -151,7 +151,7 @@
are part of a published Starlark ruleset.
To get the same behavior as for Starlark rules, wrap the label strings with the
-[`Label`](/rules/lib/Label#Label) constructor:
+[`Label`](/rules/lib/builtins/Label#Label) constructor:
```python
# @my_ruleset//rules:defs.bzl
@@ -191,7 +191,7 @@
the rule `foo` is created (due to a name conflict), which will show you the
full stack trace.
-* You can also use [print](/rules/lib/globals#print) for debugging. It displays
+* You can also use [print](/rules/lib/globals/all#print) for debugging. It displays
the message as a `DEBUG` log line during the loading phase. Except in rare
cases, either remove `print` calls, or make them conditional under a
`debugging` parameter that defaults to `False` before submitting the code to
@@ -199,7 +199,7 @@
## Errors {:#errors}
-If you want to throw an error, use the [fail](/rules/lib/globals#fail) function.
+If you want to throw an error, use the [fail](/rules/lib/globals/all#fail) function.
Explain clearly to the user what went wrong and how to fix their `BUILD` file.
It is not possible to catch an error.
diff --git a/site/en/extending/platforms.md b/site/en/extending/platforms.md
index fa8e4e6..3fa20dc 100644
--- a/site/en/extending/platforms.md
+++ b/site/en/extending/platforms.md
@@ -233,7 +233,7 @@
### Detecting incompatible targets using `bazel cquery` {:#cquery-incompatible-target-detection}
You can use the
-[`IncompatiblePlatformProvider`](/rules/lib/IncompatiblePlatformProvider)
+[`IncompatiblePlatformProvider`](/rules/lib/providers/IncompatiblePlatformProvider)
in `bazel cquery`'s [Starlark output
format](/query/cquery#output-format-definition) to distinguish
incompatible targets from compatible ones.
diff --git a/site/en/extending/repo.md b/site/en/extending/repo.md
index 526ad86..d841f44 100644
--- a/site/en/extending/repo.md
+++ b/site/en/extending/repo.md
@@ -18,7 +18,7 @@
## Repository rule creation
In a `.bzl` file, use the
-[repository_rule](/rules/lib/globals#repository_rule) function to create a new
+[repository_rule](/rules/lib/globals/bzl#repository_rule) function to create a new
repository rule and store it in a global variable.
A custom repository rule can be used just like a native repository rule. It
@@ -71,7 +71,7 @@
The input parameter `repository_ctx` can be used to
access attribute values, and non-hermetic functions (finding a binary,
executing a binary, creating a file in the repository or downloading a file
-from the Internet). See [the library](/rules/lib/repository_ctx) for more
+from the Internet). See [the library](/rules/lib/builtins/repository_ctx) for more
context. Example:
```python
@@ -102,7 +102,7 @@
`WORKSPACE` file.
* The Starlark code comprising the implementation of the repository.
* The value of any environment variable declared with the `environ`
- attribute of the [`repository_rule`](/rules/lib/globals#repository_rule).
+ attribute of the [`repository_rule`](/rules/lib/globals/bzl#repository_rule).
The values of these environment variables can be hard-wired on the command
line with the
[`--action_env`](/reference/command-line-reference#flag--action_env)
diff --git a/site/en/extending/rules.md b/site/en/extending/rules.md
index 440ad0c..e4f5ece 100644
--- a/site/en/extending/rules.md
+++ b/site/en/extending/rules.md
@@ -50,7 +50,7 @@
## Rule creation
-In a `.bzl` file, use the [rule](/rules/lib/globals#rule) function to define a new
+In a `.bzl` file, use the [rule](/rules/lib/globals/bzl#rule) function to define a new
rule, and store the result in a global variable. The call to `rule` specifies
[attributes](#attributes) and an
[implementation function](#implementation_function):
@@ -103,7 +103,7 @@
targets, creating a graph of dependencies.
Rule-specific attributes, such as `srcs` or `deps`, are defined by passing a map
-from attribute names to schemas (created using the [`attr`](/rules/lib/attr)
+from attribute names to schemas (created using the [`attr`](/rules/lib/toplevel/attr)
module) to the `attrs` parameter of `rule`.
[Common attributes](/reference/be/common-definitions#common-attributes), such as
`name` and `visibility`, are implicitly added to all rules. Additional
@@ -144,12 +144,12 @@
These are examples of *dependency attributes*. Any attribute that specifies
an input label (those defined with
-[`attr.label_list`](/rules/lib/attr#label_list),
-[`attr.label`](/rules/lib/attr#label), or
-[`attr.label_keyed_string_dict`](/rules/lib/attr#label_keyed_string_dict))
+[`attr.label_list`](/rules/lib/toplevel/attr#label_list),
+[`attr.label`](/rules/lib/toplevel/attr#label), or
+[`attr.label_keyed_string_dict`](/rules/lib/toplevel/attr#label_keyed_string_dict))
specifies dependencies of a certain type
between a target and the targets whose labels (or the corresponding
-[`Label`](/rules/lib/Label) objects) are listed in that attribute when the target
+[`Label`](/rules/lib/builtins/Label) objects) are listed in that attribute when the target
is defined. The repository, and possibly the path, for these labels is resolved
relative to the defined target.
@@ -220,8 +220,8 @@
### Output attributes
-*Output attributes*, such as [`attr.output`](/rules/lib/attr#output) and
-[`attr.output_list`](/rules/lib/attr#output_list), declare an output file that the
+*Output attributes*, such as [`attr.output`](/rules/lib/toplevel/attr#output) and
+[`attr.output_list`](/rules/lib/toplevel/attr#output_list), declare an output file that the
target generates. These differ from dependency attributes in two ways:
* They define output file targets instead of referring to targets defined
@@ -250,16 +250,16 @@
with `_impl`.
Implementation functions take exactly one parameter: a
-[rule context](/rules/lib/ctx), conventionally named `ctx`. They return a list of
+[rule context](/rules/lib/builtins/ctx), conventionally named `ctx`. They return a list of
[providers](#providers).
### Targets
-Dependencies are represented at analysis time as [`Target`](/rules/lib/Target)
+Dependencies are represented at analysis time as [`Target`](/rules/lib/builtins/Target)
objects. These objects contain the [providers](#providers) generated when the
target's implementation function was executed.
-[`ctx.attr`](/rules/lib/ctx#attr) has fields corresponding to the names of each
+[`ctx.attr`](/rules/lib/builtins/ctx#attr) has fields corresponding to the names of each
dependency attribute, containing `Target` objects representing each direct
dependency via that attribute. For `label_list` attributes, this is a list of
`Targets`. For `label` attributes, this is a single `Target` or `None`.
@@ -272,7 +272,7 @@
Those can be accessed using index notation (`[]`), with the type of provider as
a key. These can be [custom providers](#custom_providers) defined in Starlark or
-[providers for native rules](/rules/lib/starlark-provider) available as Starlark
+[providers for native rules](/rules/lib/providers) available as Starlark
global variables.
For example, if a rule takes header files via a `hdrs` attribute and provides
@@ -285,7 +285,7 @@
transitive_headers = [hdr[ExampleInfo].headers for hdr in ctx.attr.hdrs]
```
-For the legacy style in which a [`struct`](/rules/lib/struct) is returned from a
+For the legacy style in which a [`struct`](/rules/lib/builtins/struct) is returned from a
target's implementation function instead of a list of provider objects:
```python
@@ -303,10 +303,10 @@
### Files
-Files are represented by [`File`](/rules/lib/File) objects. Since Bazel does not
+Files are represented by [`File`](/rules/lib/builtins/File) objects. Since Bazel does not
perform file I/O during the analysis phase, these objects cannot be used to
directly read or write file content. Rather, they are passed to action-emitting
-functions (see [`ctx.actions`](/rules/lib/actions)) to construct pieces of the
+functions (see [`ctx.actions`](/rules/lib/builtins/actions)) to construct pieces of the
action graph.
A `File` can either be a source file or a generated file. Each generated file
@@ -314,7 +314,7 @@
any action.
For each dependency attribute, the corresponding field of
-[`ctx.files`](/rules/lib/ctx#files) contains a list of the default outputs of all
+[`ctx.files`](/rules/lib/builtins/ctx#files) contains a list of the default outputs of all
dependencies via that attribute:
```python
@@ -325,9 +325,9 @@
...
```
-[`ctx.file`](/rules/lib/ctx#file) contains a single `File` or `None` for
+[`ctx.file`](/rules/lib/builtins/ctx#file) contains a single `File` or `None` for
dependency attributes whose specs set `allow_single_file=True`.
-[`ctx.executable`](/rules/lib/ctx#executable) behaves the same as `ctx.file`, but only
+[`ctx.executable`](/rules/lib/builtins/ctx#executable) behaves the same as `ctx.file`, but only
contains fields for dependency attributes whose specs set `executable=True`.
### Declaring outputs
@@ -335,10 +335,10 @@
During the analysis phase, a rule's implementation function can create outputs.
Since all labels have to be known during the loading phase, these additional
outputs have no labels. `File` objects for outputs can be created using
-[`ctx.actions.declare_file`](/rules/lib/actions#declare_file) and
-[`ctx.actions.declare_directory`](/rules/lib/actions#declare_directory). Often,
+[`ctx.actions.declare_file`](/rules/lib/builtins/actions#declare_file) and
+[`ctx.actions.declare_directory`](/rules/lib/builtins/actions#declare_directory). Often,
the names of outputs are based on the target's name,
-[`ctx.label.name`](/rules/lib/ctx#label):
+[`ctx.label.name`](/rules/lib/builtins/ctx#label):
```python
def _example_library_impl(ctx):
@@ -349,7 +349,7 @@
For *predeclared outputs*, like those created for
[output attributes](#output_attributes), `File` objects instead can be retrieved
-from the corresponding fields of [`ctx.outputs`](/rules/lib/ctx#outputs).
+from the corresponding fields of [`ctx.outputs`](/rules/lib/builtins/ctx#outputs).
### Actions
@@ -360,16 +360,16 @@
the linker must be called after the compiler.
General-purpose functions that create actions are defined in
-[`ctx.actions`](/rules/lib/actions):
+[`ctx.actions`](/rules/lib/builtins/actions):
-* [`ctx.actions.run`](/rules/lib/actions#run), to run an executable.
-* [`ctx.actions.run_shell`](/rules/lib/actions#run_shell), to run a shell
+* [`ctx.actions.run`](/rules/lib/builtins/actions#run), to run an executable.
+* [`ctx.actions.run_shell`](/rules/lib/builtins/actions#run_shell), to run a shell
command.
-* [`ctx.actions.write`](/rules/lib/actions#write), to write a string to a file.
-* [`ctx.actions.expand_template`](/rules/lib/actions#expand_template), to
+* [`ctx.actions.write`](/rules/lib/builtins/actions#write), to write a string to a file.
+* [`ctx.actions.expand_template`](/rules/lib/builtins/actions#expand_template), to
generate a file from a template.
-[`ctx.actions.args`](/rules/lib/actions#args) can be used to efficiently
+[`ctx.actions.args`](/rules/lib/builtins/actions#args) can be used to efficiently
accumulate the arguments for actions. It avoids flattening depsets until
execution time:
@@ -434,13 +434,13 @@
Since a rule's implementation function can only read providers from the
instantiated target's immediate dependencies, rules need to forward any
information from a target's dependencies that needs to be known by a target's
-consumers, generally by accumulating that into a [`depset`](/rules/lib/depset).
+consumers, generally by accumulating that into a [`depset`](/rules/lib/builtins/depset).
A target's providers are specified by a list of `Provider` objects returned by
the implementation function.
Old implementation functions can also be written in a legacy style where the
-implementation function returns a [`struct`](/rules/lib/struct) instead of list of
+implementation function returns a [`struct`](/rules/lib/builtins/struct) instead of list of
provider objects. This style is strongly discouraged and rules should be
[migrated away from it](#migrating_from_legacy_providers).
@@ -452,7 +452,7 @@
will be built by the command `bazel build //pkg:foo`.
Default outputs are specified by the `files` parameter of
-[`DefaultInfo`](/rules/lib/DefaultInfo):
+[`DefaultInfo`](/rules/lib/providers/DefaultInfo):
```python
def _example_library_impl(ctx):
@@ -483,8 +483,8 @@
environment for the binary so it can access the runfiles during runtime.
Runfiles can be added manually during rule creation.
-[`runfiles`](/rules/lib/runfiles) objects can be created by the `runfiles` method
-on the rule context, [`ctx.runfiles`](/rules/lib/ctx#runfiles) and passed to the
+[`runfiles`](/rules/lib/builtins/runfiles) objects can be created by the `runfiles` method
+on the rule context, [`ctx.runfiles`](/rules/lib/builtins/ctx#runfiles) and passed to the
`runfiles` parameter on `DefaultInfo`. The executable output of
[executable rules](#executable-rules) is implicitly added to the runfiles.
@@ -517,7 +517,7 @@
#### Custom providers
-Providers can be defined using the [`provider`](/rules/lib/globals#provider)
+Providers can be defined using the [`provider`](/rules/lib/globals/bzl#provider)
function to convey rule-specific information:
```python
@@ -556,7 +556,7 @@
obtaining an instance.
This is done by passing an `init` callback to the
-[`provider`](/rules/lib/globals.html#provider) function. If this callback is given, the
+[`provider`](/rules/lib/globals/bzl.html#provider) function. If this callback is given, the
return type of `provider()` changes to be a tuple of two values: the provider
symbol that is the ordinary return value when `init` is not used, and a "raw
constructor".
@@ -638,8 +638,8 @@
Executable rules define targets that can be invoked by a `bazel run` command.
Test rules are a special kind of executable rule whose targets can also be
invoked by a `bazel test` command. Executable and test rules are created by
-setting the respective [`executable`](/rules/lib/globals#rule.executable) or
-[`test`](/rules/lib/globals#rule.test) argument to `True` in the call to `rule`:
+setting the respective [`executable`](/rules/lib/globals/bzl#rule.executable) or
+[`test`](/rules/lib/globals/bzl#rule.test) argument to `True` in the call to `rule`:
```python
example_binary = rule(
@@ -662,7 +662,7 @@
Both kinds of rules must produce an executable output file (which may or may not
be predeclared) that will be invoked by the `run` or `test` commands. To tell
Bazel which of a rule's outputs to use as this executable, pass it as the
-`executable` argument of a returned [`DefaultInfo`](/rules/lib/DefaultInfo)
+`executable` argument of a returned [`DefaultInfo`](/rules/lib/providers/DefaultInfo)
provider. That `executable` is added to the default outputs of the rule (so you
don't need to pass that to both `executable` and `files`). It's also implicitly
added to the [runfiles](#runfiles):
@@ -678,10 +678,10 @@
```
The action that generates this file must set the executable bit on the file. For
-a [`ctx.actions.run`](/rules/lib/actions#run) or
-[`ctx.actions.run_shell`](/rules/lib/actions#run_shell) action this should be done
+a [`ctx.actions.run`](/rules/lib/builtins/actions#run) or
+[`ctx.actions.run_shell`](/rules/lib/builtins/actions#run_shell) action this should be done
by the underlying tool that is invoked by the action. For a
-[`ctx.actions.write`](/rules/lib/actions#write) action, pass `is_executable=True`.
+[`ctx.actions.write`](/rules/lib/builtins/actions#write) action, pass `is_executable=True`.
As [legacy behavior](#deprecated_predeclared_outputs), executable rules have a
special `ctx.outputs.executable` predeclared output. This file serves as the
@@ -726,7 +726,7 @@
```
The path to a `File` under the runfiles directory corresponds to
-[`File.short_path`](/rules/lib/File#short_path).
+[`File.short_path`](/rules/lib/builtins/File#short_path).
The binary executed directly by `bazel` is adjacent to the root of the
`runfiles` directory. However, binaries called *from* the runfiles can't make
@@ -751,8 +751,8 @@
be explicitly requested on the command line. Rules can specify predeclared
outputs via [output attributes](#output_attributes). In that case, the user
explicitly chooses labels for outputs when they instantiate the rule. To obtain
-[`File`](/rules/lib/File) objects for output attributes, use the corresponding
-attribute of [`ctx.outputs`](/rules/lib/ctx#outputs). Rules can
+[`File`](/rules/lib/builtins/File) objects for output attributes, use the corresponding
+attribute of [`ctx.outputs`](/rules/lib/builtins/ctx#outputs). Rules can
[implicitly define predeclared outputs](#deprecated_predeclared_outputs) based
on the target name as well, but this feature is deprecated.
@@ -766,7 +766,7 @@
group.
Output groups can be specified with the
-[`OutputGroupInfo`](/rules/lib/OutputGroupInfo) provider. Note that unlike many
+[`OutputGroupInfo`](/rules/lib/providers/OutputGroupInfo) provider. Note that unlike many
built-in providers, `OutputGroupInfo` can take parameters with arbitrary names
to define output groups with that name:
@@ -858,7 +858,7 @@
### Configuration fragments
Rules may access
-[configuration fragments](/rules/lib/starlark-configuration-fragment) such as
+[configuration fragments](/rules/lib/fragments) such as
`cpp`, `java` and `jvm`. However, all required fragments must be declared in
order to avoid access errors:
@@ -925,7 +925,7 @@
If a rule implementation adds coverage instrumentation at build time, it needs
to account for that in its implementation function.
-[ctx.coverage_instrumented](/rules/lib/ctx#coverage_instrumented) returns true in
+[ctx.coverage_instrumented](/rules/lib/builtins/ctx#coverage_instrumented) returns true in
coverage mode if a target's sources should be instrumented:
```python
@@ -936,7 +936,7 @@
Logic that always needs to be on in coverage mode (whether a target's sources
specifically are instrumented or not) can be conditioned on
-[ctx.configuration.coverage_enabled](/rules/lib/configuration#coverage_enabled).
+[ctx.configuration.coverage_enabled](/rules/lib/builtins/configuration#coverage_enabled).
If the rule directly includes sources from its dependencies before compilation
(such as header files), it may also need to turn on compile-time instrumentation if
@@ -953,7 +953,7 @@
Rules also should provide information about which attributes are relevant for
coverage with the `InstrumentedFilesInfo` provider, constructed using
-[`coverage_common.instrumented_files_info`](/rules/lib/coverage_common#instrumented_files_info).
+[`coverage_common.instrumented_files_info`](/rules/lib/toplevel/coverage_common#instrumented_files_info).
The `dependency_attributes` parameter of `instrumented_files_info` should list
all runtime dependency attributes, including code dependencies like `deps` and
data dependencies like `data`. The `source_attributes` parameter should list the
@@ -1139,7 +1139,7 @@
There are two **deprecated** ways of using predeclared outputs:
-* The [`outputs`](/rules/lib/globals#rule.outputs) parameter of `rule` specifies
+* The [`outputs`](/rules/lib/globals/bzl#rule.outputs) parameter of `rule` specifies
a mapping between output attribute names and string templates for generating
predeclared output labels. Prefer using non-predeclared outputs and
explicitly adding outputs to `DefaultInfo.files`. Use the rule target's
@@ -1155,12 +1155,12 @@
### Runfiles features to avoid
-[`ctx.runfiles`](/rules/lib/ctx#runfiles) and the [`runfiles`](/rules/lib/runfiles)
+[`ctx.runfiles`](/rules/lib/builtins/ctx#runfiles) and the [`runfiles`](/rules/lib/builtins/runfiles)
type have a complex set of features, many of which are kept for legacy reasons.
The following recommendations help reduce complexity:
* **Avoid** use of the `collect_data` and `collect_default` modes of
- [`ctx.runfiles`](/rules/lib/ctx#runfiles). These modes implicitly collect
+ [`ctx.runfiles`](/rules/lib/builtins/ctx#runfiles). These modes implicitly collect
runfiles across certain hardcoded dependency edges in confusing ways.
Instead, add files using the `files` or `transitive_files` parameters of
`ctx.runfiles`, or by merging in runfiles from dependencies with
@@ -1218,14 +1218,14 @@
* The fields `files`, `runfiles`, `data_runfiles`, `default_runfiles`, and
`executable` correspond to the same-named fields of
- [`DefaultInfo`](/rules/lib/DefaultInfo). It is not allowed to specify any of
+ [`DefaultInfo`](/rules/lib/providers/DefaultInfo). It is not allowed to specify any of
these fields while also returning a `DefaultInfo` provider.
* The field `output_groups` takes a struct value and corresponds to an
- [`OutputGroupInfo`](/rules/lib/OutputGroupInfo).
+ [`OutputGroupInfo`](/rules/lib/providers/OutputGroupInfo).
-In [`provides`](/rules/lib/globals#rule.provides) declarations of rules, and in
-[`providers`](/rules/lib/attr#label_list.providers) declarations of dependency
+In [`provides`](/rules/lib/globals/bzl#rule.provides) declarations of rules, and in
+[`providers`](/rules/lib/toplevel/attr#label_list.providers) declarations of dependency
attributes, legacy providers are passed in as strings and modern providers are
passed in by their `*Info` symbol. Be sure to change from strings to symbols
when migrating. For complex or large rule sets where it is difficult to update
diff --git a/site/en/extending/toolchains.md b/site/en/extending/toolchains.md
index 4e64243..879aed1 100644
--- a/site/en/extending/toolchains.md
+++ b/site/en/extending/toolchains.md
@@ -173,7 +173,7 @@
```
`ctx.toolchains["//bar_tools:toolchain_type"]` returns the
-[`ToolchainInfo` provider](/rules/lib/platform_common#ToolchainInfo)
+[`ToolchainInfo` provider](/rules/lib/toplevel/platform_common#ToolchainInfo)
of whatever target Bazel resolved the toolchain dependency to. The fields of the
`ToolchainInfo` object are set by the underlying tool's rule; in the next
section, this rule is defined such that there is a `barcinfo` field that wraps
@@ -207,7 +207,7 @@
When an optional toolchain type cannot be resolved, analysis continues, and the
result of `ctx.toolchains["//bar_tools:toolchain_type"]` is `None`.
-The [`config_common.toolchain_type`](/rules/lib/config_common#toolchain_type)
+The [`config_common.toolchain_type`](/rules/lib/toplevel/config_common#toolchain_type)
function defaults to mandatory.
The following forms can be used:
@@ -407,7 +407,7 @@
)
```
-The use of [`attr.label`](/rules/lib/attr#label) is the same as for a standard rule,
+The use of [`attr.label`](/rules/lib/toplevel/attr#label) is the same as for a standard rule,
but the meaning of the `cfg` parameter is slightly different.
The dependency from a target (called the "parent") to a toolchain via toolchain
@@ -486,9 +486,9 @@
The available execution platforms and toolchains are gathered from the
`WORKSPACE` file via
-[`register_execution_platforms`](/rules/lib/globals#register_execution_platforms)
+[`register_execution_platforms`](/rules/lib/globals/workspace#register_execution_platforms)
and
-[`register_toolchains`](/rules/lib/globals#register_toolchains).
+[`register_toolchains`](/rules/lib/globals/workspace#register_toolchains).
Additional execution platforms and toolchains may also be specified on the
command line via
[`--extra_execution_platforms`](/reference/command-line-reference#flag--extra_execution_platforms)
@@ -510,7 +510,7 @@
1. If the target being built specifies the
[`exec_compatible_with` attribute](/reference/be/common-definitions#common.exec_compatible_with)
(or its rule definition specifies the
- [`exec_compatible_with` argument](/rules/lib/globals#rule.exec_compatible_with)),
+ [`exec_compatible_with` argument](/rules/lib/globals/bzl#rule.exec_compatible_with)),
the list of available execution platforms is filtered to remove
any that do not match the execution constraints.
diff --git a/site/en/external/advanced.md b/site/en/external/advanced.md
index 6e4f472..f77df7f 100644
--- a/site/en/external/advanced.md
+++ b/site/en/external/advanced.md
@@ -114,7 +114,7 @@
names here. Alternatively, use the
[`--override_module`](/reference/command-line-reference#flag--override_module)
flag to override a module to a local directory, similar to the
-[`local_path_override`](/rules/lib/globals#local_path_override) directive in
+[`local_path_override`](/rules/lib/globals/module#local_path_override) directive in
`MODULE.bazel`.
## Using proxies
@@ -165,8 +165,8 @@
For true offline builds, where a different entity supplies all needed files,
Bazel supports the option `--distdir`. This flag tells Bazel to look first into
the directories specified by that option when a repository rule asks Bazel to
-fetch a file with [`ctx.download`](/rules/lib/repository_ctx#download) or
-[`ctx.download_and_extract`](/rules/lib/repository_ctx#download_and_extract). By
+fetch a file with [`ctx.download`](/rules/lib/builtins/repository_ctx#download) or
+[`ctx.download_and_extract`](/rules/lib/builtins/repository_ctx#download_and_extract). By
providing a hash sum of the file needed, Bazel looks for a file matching the
basename of the first URL, and uses the local copy if the hash matches.
diff --git a/site/en/external/extension.md b/site/en/external/extension.md
index 90f5490..57321ac 100644
--- a/site/en/external/extension.md
+++ b/site/en/external/extension.md
@@ -23,7 +23,7 @@
Extensions are hosted in Bazel modules themselves. To use an extension in a
module, first add a `bazel_dep` on the module hosting the extension, and then
-call the [`use_extension`](/rules/lib/globals#use_extension) built-in function
+call the [`use_extension`](/rules/lib/globals/module#use_extension) built-in function
to bring it into scope. Consider the following example — a snippet from a
`MODULE.bazel` file to use the "maven" extension defined in the
[`rules_jvm_external`](https://github.com/bazelbuild/rules_jvm_external){:.external}
@@ -48,7 +48,7 @@
exclusions = ["com.google.j2objc:j2objc-annotations"])
```
-Use the [`use_repo`](/rules/lib/globals#use_repo) directive to bring repos
+Use the [`use_repo`](/rules/lib/globals/module#use_repo) directive to bring repos
generated by the extension into the scope of the current module.
```python
@@ -64,9 +64,9 @@
## Extension definition
You can define module extensions similarly to repo rules, using the
-[`module_extension`](/rules/lib/globals#module_extension) function. However,
+[`module_extension`](/rules/lib/globals/bzl#module_extension) function. However,
while repo rules have a number of attributes, module extensions have
-[`tag_class`es](/rules/lib/globals#tag_class), each of which has a number of
+[`tag_class`es](/rules/lib/globals/bzl#tag_class), each of which has a number of
attributes. The tag classes define schemas for tags used by this extension. For
example, the "maven" extension above might be defined like this:
@@ -85,7 +85,7 @@
specified using the specified attribute schema.
The implementation function of module extensions are similar to those of repo
-rules, except that they get a [`module_ctx`](/rules/lib/module_ctx) object,
+rules, except that they get a [`module_ctx`](/rules/lib/builtins/module_ctx) object,
which grants access to all modules using the extension and all pertinent tags.
The implementation function then calls repo rules to generate repos.
@@ -151,8 +151,8 @@
several repo visibility rules:
* A Bazel module repo can see all repos introduced in its `MODULE.bazel` file
- via [`bazel_dep`](/rules/lib/globals#bazel_dep) and
- [`use_repo`](/rules/lib/globals#use_repo).
+ via [`bazel_dep`](/rules/lib/globals/module#bazel_dep) and
+ [`use_repo`](/rules/lib/globals/module#use_repo).
* A repo generated by a module extension can see all repos visible to the
module that hosts the extension, *plus* all other repos generated by the
same module extension (using the names specified in the repo rule calls as
diff --git a/site/en/external/module.md b/site/en/external/module.md
index d9f61c0..a273acb 100644
--- a/site/en/external/module.md
+++ b/site/en/external/module.md
@@ -22,7 +22,7 @@
bazel_dep(name = "protobuf", version = "3.19.0")
```
-<!-- TODO(wyv): add link to MODULE.bazel globals -->
+See the [full list](/rules/lib/globals/module) of directives available in `MODULE.bazel` files.
To perform module resolution, Bazel starts by reading the root module's
`MODULE.bazel` file, and then repeatedly requests any dependency's
@@ -118,7 +118,7 @@
### Single-version override
-The [`single_version_override`](/rules/lib/globals#single_version_override)
+The [`single_version_override`](/rules/lib/globals/module#single_version_override)
serves multiple purposes:
* With the `version` attribute, you can pin a dependency to a specific
@@ -134,7 +134,7 @@
### Multiple-version override
-A [`multiple_version_override`](/rules/lib/globals#multiple_version_override)
+A [`multiple_version_override`](/rules/lib/globals/module#multiple_version_override)
can be specified to allow multiple versions of the same module to coexist in the
resolved dependency graph.
@@ -169,9 +169,9 @@
Bazel supports the following non-registry overrides:
-* [`archive_override`](/rules/lib/globals#archive_override)
-* [`git_override`](/rules/lib/globals#git_override)
-* [`local_path_override`](/rules/lib/globals#local_path_override)
+* [`archive_override`](/rules/lib/globals/module#archive_override)
+* [`git_override`](/rules/lib/globals/module#git_override)
+* [`local_path_override`](/rules/lib/globals/module#local_path_override)
## Repository names and strict deps
@@ -184,7 +184,7 @@
The [apparent name](/external/overview#apparent_repository_name) of a repo
backing a module to its direct dependents defaults to its module name, unless
-the `repo_name` attribute of the [`bazel_dep`](/rules/lib/globals#bazel_dep)
+the `repo_name` attribute of the [`bazel_dep`](/rules/lib/globals/module#bazel_dep)
directive says otherwise. Note that this means a module can only find its direct
dependencies. This helps prevent accidental breakages due to changes in
transitive dependencies.
diff --git a/site/en/external/overview.md b/site/en/external/overview.md
index fae1c1b..f497508 100644
--- a/site/en/external/overview.md
+++ b/site/en/external/overview.md
@@ -166,7 +166,7 @@
system, by default, the canonical name of a repo is also its apparent name to
all other repos.
-<!-- TODO(wyv): add link to WORKSPACE globals -->
+See the [full list](/rules/lib/globals/workspace) of functions available in `WORKSPACE` files.
### Shortcomings of the `WORKSPACE` system
diff --git a/site/en/query/cquery.md b/site/en/query/cquery.md
index 7cac978..10d10d3 100644
--- a/site/en/query/cquery.md
+++ b/site/en/query/cquery.md
@@ -389,7 +389,7 @@
function for each configured target in the query result, and prints the value
returned by the call. The `--starlark:file` flag specifies the location of a
Starlark file that defines a function named `format` with a single parameter,
-`target`. This function is called for each [Target](/rules/lib/Target)
+`target`. This function is called for each [Target](/rules/lib/builtins/Target)
in the query result. Alternatively, for convenience, you may specify just the
body of a function declared as `def format(target): return expr` by using the
`--starlark:expr` flag.
diff --git a/site/en/remote/rules.md b/site/en/remote/rules.md
index 15ea017..16d96ae 100644
--- a/site/en/remote/rules.md
+++ b/site/en/remote/rules.md
@@ -136,7 +136,7 @@
build to fail on the remote execution platform as Bazel will not be able to
locate them. Instead, create symlinks using standard build actions so that
the symlinked tools and libraries are accessible from Bazel's `runfiles`
- tree. Do not use [`repository_ctx.symlink`](/rules/lib/repository_ctx#symlink)
+ tree. Do not use [`repository_ctx.symlink`](/rules/lib/builtins/repository_ctx#symlink)
to symlink target files outside of the external repo directory.
* **Mutating the host platform.** Avoid creating files outside of the Bazel
diff --git a/site/en/remote/workspace.md b/site/en/remote/workspace.md
index aa65553..b0afda3 100644
--- a/site/en/remote/workspace.md
+++ b/site/en/remote/workspace.md
@@ -27,7 +27,7 @@
happen in the process. All related commands are happening locally and can be a
potential source of non-hermeticity. Usually non-hermetic behavior is
introduced through
-[`repository_ctx`](/rules/lib/repository_ctx) which allows interacting
+[`repository_ctx`](/rules/lib/builtins/repository_ctx) which allows interacting
with the host machine.
Starting with Bazel 0.18, you can get a log of some potentially non-hermetic
@@ -98,7 +98,7 @@
The log consists of
[WorkspaceEvent](https://source.bazel.build/bazel/+/master:src/main/java/com/google/devtools/build/lib/bazel/debug/workspace_log.proto?q=WorkspaceEvent)
messages outlining certain potentially non-hermetic actions performed on a
-[`repository_ctx`](/rules/lib/repository_ctx).
+[`repository_ctx`](/rules/lib/builtins/repository_ctx).
The actions that have been highlighted as potentially non-hermetic are as follows:
diff --git a/site/en/rules/language.md b/site/en/rules/language.md
index 3a47d4a..76c3371 100644
--- a/site/en/rules/language.md
+++ b/site/en/rules/language.md
@@ -9,7 +9,7 @@
This page is an overview of [Starlark](https://github.com/bazelbuild/starlark),
formerly known as Skylark, the language used in Bazel. For a complete list of
-functions and types, see the [Bazel API reference](/rules/lib/starlark-overview).
+functions and types, see the [Bazel API reference](/rules/lib/overview).
For more information about the language, see [Starlark's GitHub repo](https://github.com/bazelbuild/starlark/).
@@ -100,7 +100,7 @@
[Native functions](/reference/be/functions) and [native rules](
/reference/be/overview#language-specific-native-rules) are global symbols in
`BUILD` files. `bzl` files need to load them using the [`native` module](
-https://bazel.build/rules/lib/native).
+/rules/lib/toplevel/native).
There are two syntactic restrictions in `BUILD` files: 1) declaring functions is
illegal, and 2) `*args` and `**kwargs` arguments are not allowed.
diff --git a/site/en/tutorials/ccp-toolchain-config.md b/site/en/tutorials/ccp-toolchain-config.md
index 5c5797cd..df2d47e 100644
--- a/site/en/tutorials/ccp-toolchain-config.md
+++ b/site/en/tutorials/ccp-toolchain-config.md
@@ -137,7 +137,7 @@
```
Bazel discovered that the `--crosstool_top` flag points to a rule that
- doesn't provide the necessary [`ToolchainInfo`](/rules/lib/ToolchainInfo)
+ doesn't provide the necessary [`ToolchainInfo`](/rules/lib/providers/ToolchainInfo)
provider. So you need to point `--crosstool_top` to a rule that does provide
`ToolchainInfo` - that is the `cc_toolchain_suite` rule. In the
`toolchain/BUILD` file, replace the empty filegroup with the following:
@@ -328,7 +328,7 @@
Bazel needs to know where to search for included headers. There are
multiple ways to solve this, such as using the `includes` attribute of
`cc_binary`, but here this is solved at the toolchain level with the
- [`cxx_builtin_include_directories`](/rules/lib/cc_common#create_cc_toolchain_config_info)
+ [`cxx_builtin_include_directories`](/rules/lib/toplevel/cc_common#create_cc_toolchain_config_info)
parameter of `cc_common.create_cc_toolchain_config_info`. Beware that if
you are using a different version of `clang`, the include path will be
different. These paths may also be different depending on the distribution.
diff --git a/src/main/java/com/google/devtools/build/docgen/ApiExporter.java b/src/main/java/com/google/devtools/build/docgen/ApiExporter.java
index 7b9e1fc..1d92e0a 100644
--- a/src/main/java/com/google/devtools/build/docgen/ApiExporter.java
+++ b/src/main/java/com/google/devtools/build/docgen/ApiExporter.java
@@ -14,15 +14,17 @@
package com.google.devtools.build.docgen;
import com.google.common.collect.ImmutableList;
+import com.google.common.collect.ImmutableMap;
+import com.google.devtools.build.docgen.StarlarkDocumentationProcessor.Category;
import com.google.devtools.build.docgen.builtin.BuiltinProtos.ApiContext;
import com.google.devtools.build.docgen.builtin.BuiltinProtos.Builtins;
import com.google.devtools.build.docgen.builtin.BuiltinProtos.Callable;
import com.google.devtools.build.docgen.builtin.BuiltinProtos.Param;
import com.google.devtools.build.docgen.builtin.BuiltinProtos.Type;
import com.google.devtools.build.docgen.builtin.BuiltinProtos.Value;
-import com.google.devtools.build.docgen.starlark.StarlarkBuiltinDoc;
import com.google.devtools.build.docgen.starlark.StarlarkConstructorMethodDoc;
import com.google.devtools.build.docgen.starlark.StarlarkDocExpander;
+import com.google.devtools.build.docgen.starlark.StarlarkDocPage;
import com.google.devtools.build.docgen.starlark.StarlarkMethodDoc;
import com.google.devtools.build.docgen.starlark.StarlarkParamDoc;
import com.google.devtools.common.options.OptionsParser;
@@ -33,6 +35,7 @@
import java.util.ArrayList;
import java.util.Collections;
import java.util.HashMap;
+import java.util.Iterator;
import java.util.List;
import java.util.Map;
import java.util.Map.Entry;
@@ -51,51 +54,43 @@
public class ApiExporter {
private static void appendTypes(
- Builtins.Builder builtins,
- Map<String, StarlarkBuiltinDoc> types,
- List<RuleDocumentation> nativeRules)
+ Builtins.Builder builtins, StarlarkDocPage docPage, List<RuleDocumentation> nativeRules)
throws BuildEncyclopediaDocException {
-
- for (Entry<String, StarlarkBuiltinDoc> modEntry : types.entrySet()) {
- StarlarkBuiltinDoc mod = modEntry.getValue();
-
- Type.Builder type = Type.newBuilder();
- type.setName(mod.getName());
- type.setDoc(mod.getDocumentation());
- for (StarlarkMethodDoc meth : mod.getJavaMethods()) {
- // Constructors are exported as global symbols.
- if (!(meth instanceof StarlarkConstructorMethodDoc)) {
- Value.Builder value = collectMethodInfo(meth);
+ Type.Builder type = Type.newBuilder();
+ type.setName(docPage.getName());
+ type.setDoc(docPage.getDocumentation());
+ for (StarlarkMethodDoc meth : docPage.getJavaMethods()) {
+ // Constructors are exported as global symbols.
+ if (!(meth instanceof StarlarkConstructorMethodDoc)) {
+ Value.Builder value = collectMethodInfo(meth);
+ if (type.getName().equals("native")) {
// Methods from the native package are available as top level functions in BUILD files.
- if (mod.getName().equals("native")) {
- value.setApiContext(ApiContext.BUILD);
- builtins.addGlobal(value);
+ value.setApiContext(ApiContext.BUILD);
+ builtins.addGlobal(value);
- value.setApiContext(ApiContext.BZL);
- type.addField(value);
- } else {
- value.setApiContext(ApiContext.ALL);
- type.addField(value);
- }
+ value.setApiContext(ApiContext.BZL);
+ type.addField(value);
+ } else {
+ value.setApiContext(ApiContext.ALL);
+ type.addField(value);
}
}
- // Native rules are available in BZL file as methods of the native package.
- if (mod.getName().equals("native")) {
- for (RuleDocumentation rule : nativeRules) {
- Value.Builder field = collectRuleInfo(rule);
- field.setApiContext(ApiContext.BZL);
- type.addField(field);
- }
- }
- builtins.addType(type);
}
+ if (type.getName().equals("native")) {
+ for (RuleDocumentation rule : nativeRules) {
+ Value.Builder field = collectRuleInfo(rule);
+ field.setApiContext(ApiContext.BZL);
+ type.addField(field);
+ }
+ }
+ builtins.addType(type);
}
private static void appendGlobals(
Builtins.Builder builtins,
Map<String, Object> globals,
Map<String, StarlarkMethodDoc> globalToDoc,
- Map<String, StarlarkBuiltinDoc> types,
+ Map<String, StarlarkConstructorMethodDoc> typeNameToConstructor,
ApiContext context) {
for (Entry<String, Object> entry : globals.entrySet()) {
String name = entry.getKey();
@@ -122,12 +117,9 @@
StarlarkMethod annotation = StarlarkAnnotations.getStarlarkMethod(selfCallMethod);
value = valueFromAnnotation(annotation);
// For constructors, we can also set the return type.
- StarlarkBuiltinDoc doc = types.get(entry.getKey());
- if (doc != null) {
- StarlarkConstructorMethodDoc constructor = doc.getConstructor();
- if (constructor != null && value.hasCallable()) {
- value.getCallableBuilder().setReturnType(constructor.getReturnType());
- }
+ StarlarkConstructorMethodDoc constructor = typeNameToConstructor.get(entry.getKey());
+ if (constructor != null && value.hasCallable()) {
+ value.getCallableBuilder().setReturnType(constructor.getReturnType());
}
} else {
value.setName(name);
@@ -353,20 +345,32 @@
options.provider,
options.inputDirs,
options.denylist);
- Map<String, StarlarkBuiltinDoc> types = symbols.getTypes();
+ ImmutableMap<Category, ImmutableList<StarlarkDocPage>> allDocPages = symbols.getAllDocPages();
Builtins.Builder builtins = Builtins.newBuilder();
- StarlarkBuiltinDoc globals = types.get("globals");
+ ImmutableList<StarlarkDocPage> globalPages = allDocPages.get(Category.GLOBAL_FUNCTION);
Map<String, StarlarkMethodDoc> globalToDoc = new HashMap<>();
- if (globals != null) {
- for (StarlarkMethodDoc meth : globals.getJavaMethods()) {
+ for (StarlarkDocPage globalPage : globalPages) {
+ for (StarlarkMethodDoc meth : globalPage.getJavaMethods()) {
globalToDoc.put(meth.getShortName(), meth);
}
}
- appendTypes(builtins, types, symbols.getNativeRules());
- appendGlobals(builtins, symbols.getGlobals(), globalToDoc, types, ApiContext.ALL);
- appendGlobals(builtins, symbols.getBzlGlobals(), globalToDoc, types, ApiContext.BZL);
+ Iterator<StarlarkDocPage> typesIterator =
+ allDocPages.entrySet().stream()
+ .filter(e -> !e.getKey().equals(Category.GLOBAL_FUNCTION))
+ .flatMap(e -> e.getValue().stream())
+ .iterator();
+ Map<String, StarlarkConstructorMethodDoc> typeNameToConstructor = new HashMap<>();
+ while (typesIterator.hasNext()) {
+ StarlarkDocPage typeDocPage = typesIterator.next();
+ appendTypes(builtins, typeDocPage, symbols.getNativeRules());
+ typeNameToConstructor.put(typeDocPage.getName(), typeDocPage.getConstructor());
+ }
+ appendGlobals(
+ builtins, symbols.getGlobals(), globalToDoc, typeNameToConstructor, ApiContext.ALL);
+ appendGlobals(
+ builtins, symbols.getBzlGlobals(), globalToDoc, typeNameToConstructor, ApiContext.BZL);
appendNativeRules(builtins, symbols.getNativeRules());
writeBuiltins(options.outputFile, builtins);
diff --git a/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java b/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java
index 825f875..0917e84 100644
--- a/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java
+++ b/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java
@@ -39,8 +39,6 @@
public static final String STARLARK_LIBRARY_TEMPLATE =
"com/google/devtools/build/docgen/templates/starlark-library.vm";
- public static final String STARLARK_NAV_TEMPLATE =
- "com/google/devtools/build/docgen/templates/starlark-nav.vm";
public static final String STARLARK_MODULE_CATEGORY_TEMPLATE =
"com/google/devtools/build/docgen/templates/starlark-category.vm";
public static final String STARLARK_OVERVIEW_TEMPLATE =
diff --git a/src/main/java/com/google/devtools/build/docgen/StarlarkDocumentationCollector.java b/src/main/java/com/google/devtools/build/docgen/StarlarkDocumentationCollector.java
index c14e5da..df6efd3 100644
--- a/src/main/java/com/google/devtools/build/docgen/StarlarkDocumentationCollector.java
+++ b/src/main/java/com/google/devtools/build/docgen/StarlarkDocumentationCollector.java
@@ -14,51 +14,47 @@
package com.google.devtools.build.docgen;
import com.google.common.base.Preconditions;
+import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;
import com.google.common.collect.Iterables;
-import com.google.devtools.build.docgen.annot.DocCategory;
+import com.google.common.collect.Maps;
+import com.google.devtools.build.docgen.StarlarkDocumentationProcessor.Category;
import com.google.devtools.build.docgen.annot.GlobalMethods;
+import com.google.devtools.build.docgen.annot.GlobalMethods.Environment;
import com.google.devtools.build.docgen.annot.StarlarkConstructor;
import com.google.devtools.build.docgen.starlark.StarlarkBuiltinDoc;
import com.google.devtools.build.docgen.starlark.StarlarkConstructorMethodDoc;
import com.google.devtools.build.docgen.starlark.StarlarkDocExpander;
+import com.google.devtools.build.docgen.starlark.StarlarkDocPage;
+import com.google.devtools.build.docgen.starlark.StarlarkGlobalsDoc;
import com.google.devtools.build.docgen.starlark.StarlarkJavaMethodDoc;
import com.google.devtools.build.lib.util.Classpath;
import com.google.devtools.build.lib.util.Classpath.ClassPathException;
import java.lang.reflect.Method;
+import java.text.Collator;
+import java.util.Comparator;
+import java.util.EnumMap;
+import java.util.HashMap;
+import java.util.Locale;
import java.util.Map;
-import java.util.TreeMap;
-import javax.annotation.Nullable;
import net.starlark.java.annot.StarlarkAnnotations;
import net.starlark.java.annot.StarlarkBuiltin;
import net.starlark.java.annot.StarlarkMethod;
import net.starlark.java.eval.Starlark;
import net.starlark.java.eval.StarlarkSemantics;
-import net.starlark.java.eval.StarlarkValue;
/** A helper class that collects Starlark module documentation. */
final class StarlarkDocumentationCollector {
- @StarlarkBuiltin(
- name = "globals",
- category = DocCategory.TOP_LEVEL_MODULE,
- doc = "Objects, functions and modules registered in the global environment.")
- private static final class TopLevelModule implements StarlarkValue {}
-
private StarlarkDocumentationCollector() {}
- /** Returns the StarlarkBuiltin annotation for the top-level Starlark module. */
- public static StarlarkBuiltin getTopLevelModule() {
- return TopLevelModule.class.getAnnotation(StarlarkBuiltin.class);
- }
+ private static ImmutableMap<Category, ImmutableList<StarlarkDocPage>> all;
- private static ImmutableMap<String, StarlarkBuiltinDoc> all;
-
- /** Applies {@link #collectModules} to all Bazel and Starlark classes. */
- static synchronized ImmutableMap<String, StarlarkBuiltinDoc> getAllModules(
+ /** Applies {@link #collectDocPages} to all Bazel and Starlark classes. */
+ static synchronized ImmutableMap<Category, ImmutableList<StarlarkDocPage>> getAllDocPages(
StarlarkDocExpander expander) throws ClassPathException {
if (all == null) {
all =
- collectModules(
+ collectDocPages(
Iterables.concat(
/*Bazel*/ Classpath.findClasses("com/google/devtools/build"),
/*Starlark*/ Classpath.findClasses("net/starlark/java")),
@@ -71,27 +67,16 @@
* Collects the documentation for all Starlark modules comprised of the given classes and returns
* a map from the name of each Starlark module to its documentation.
*/
- static ImmutableMap<String, StarlarkBuiltinDoc> collectModules(
+ static ImmutableMap<Category, ImmutableList<StarlarkDocPage>> collectDocPages(
Iterable<Class<?>> classes, StarlarkDocExpander expander) {
- Map<String, StarlarkBuiltinDoc> modules = new TreeMap<>();
- // The top level module first.
- // (This is a special case of {@link StarlarkBuiltinDoc} as it has no object name).
- StarlarkBuiltin topLevelModule = getTopLevelModule();
- modules.put(
- topLevelModule.name(),
- new StarlarkBuiltinDoc(
- topLevelModule,
- /*title=*/ "Globals",
- TopLevelModule.class,
- expander,
- /*isTopLevel=*/ true));
+ Map<Category, Map<String, StarlarkDocPage>> pages = new EnumMap<>(Category.class);
+ for (Category category : Category.values()) {
+ pages.put(category, new HashMap<>());
+ }
- // Creating module documentation is done in three passes.
// 1. Add all classes/interfaces annotated with @StarlarkBuiltin with documented = true.
for (Class<?> candidateClass : classes) {
- if (candidateClass.isAnnotationPresent(StarlarkBuiltin.class)) {
- collectStarlarkModule(candidateClass, modules, expander);
- }
+ collectStarlarkBuiltin(candidateClass, pages, expander);
}
// 2. Add all object methods and global functions.
@@ -112,175 +97,177 @@
// Note that BuiltinFunction doesn't actually have getJavaMethod.
//
for (Class<?> candidateClass : classes) {
- if (candidateClass.isAnnotationPresent(StarlarkBuiltin.class)) {
- collectModuleMethods(candidateClass, modules, expander);
- }
- if (candidateClass.isAnnotationPresent(GlobalMethods.class)
- || candidateClass.getName().equals("net.starlark.java.eval.MethodLibrary")) {
- collectDocumentedMethods(candidateClass, modules, expander);
- }
+ collectBuiltinMethods(candidateClass, pages, expander);
+ collectGlobalMethods(candidateClass, pages, expander);
}
// 3. Add all constructors.
for (Class<?> candidateClass : classes) {
- if (candidateClass.isAnnotationPresent(StarlarkBuiltin.class)
- || candidateClass.isAnnotationPresent(GlobalMethods.class)) {
- collectConstructorMethods(candidateClass, modules, expander);
- }
+ collectConstructorMethods(candidateClass, pages, expander);
}
- return ImmutableMap.copyOf(modules);
+ return ImmutableMap.copyOf(
+ Maps.transformValues(
+ pages,
+ pagesInCategory ->
+ ImmutableList.sortedCopyOf(
+ Comparator.comparing(
+ StarlarkDocPage::getTitle, Collator.getInstance(Locale.US)),
+ pagesInCategory.values())));
}
/**
- * Returns the {@link StarlarkBuiltinDoc} entry representing the collection of top level
- * functions. (This is a special case of {@link StarlarkBuiltinDoc} as it has no object name).
+ * Adds a single {@link StarlarkDocPage} entry to {@code pages} representing the given {@code
+ * builtinClass}, if it is a documented builtin.
*/
- private static StarlarkBuiltinDoc getTopLevelModuleDoc(Map<String, StarlarkBuiltinDoc> modules) {
- return modules.get(getTopLevelModule().name());
- }
-
- /**
- * Adds a single {@link StarlarkBuiltinDoc} entry to {@code modules} representing the given {@code
- * moduleClass}, if it is a documented module.
- */
- private static void collectStarlarkModule(
- Class<?> moduleClass, Map<String, StarlarkBuiltinDoc> modules, StarlarkDocExpander expander) {
- if (moduleClass.equals(TopLevelModule.class)) {
- // The top level module doc is a special case and is handled separately.
+ private static void collectStarlarkBuiltin(
+ Class<?> builtinClass,
+ Map<Category, Map<String, StarlarkDocPage>> pages,
+ StarlarkDocExpander expander) {
+ StarlarkBuiltin starlarkBuiltin = builtinClass.getAnnotation(StarlarkBuiltin.class);
+ if (starlarkBuiltin == null || !starlarkBuiltin.documented()) {
return;
}
- StarlarkBuiltin moduleAnnotation =
- Preconditions.checkNotNull(moduleClass.getAnnotation(StarlarkBuiltin.class));
+ Map<String, StarlarkDocPage> pagesInCategory = pages.get(Category.of(starlarkBuiltin));
+ StarlarkDocPage existingPage = pagesInCategory.get(starlarkBuiltin.name());
+ if (existingPage == null) {
+ pagesInCategory.put(
+ starlarkBuiltin.name(), new StarlarkBuiltinDoc(starlarkBuiltin, builtinClass, expander));
+ return;
+ }
- if (moduleAnnotation.documented()) {
- StarlarkBuiltinDoc previousModuleDoc = modules.get(moduleAnnotation.name());
- if (previousModuleDoc == null) {
- modules.put(
- moduleAnnotation.name(),
- new StarlarkBuiltinDoc(
- moduleAnnotation, moduleAnnotation.name(), moduleClass, expander));
- } else {
- // Handle a strange corner-case: If moduleClass has a subclass which is also
- // annotated with {@link StarlarkBuiltin} with the same name, and also has the same
- // module-level docstring, then the subclass takes precedence.
- // (This is useful if one module is a "common" stable module, and its subclass is
- // an experimental module that also supports all stable methods.)
- validateCompatibleModules(previousModuleDoc.getClassObject(), moduleClass);
+ // Handle a strange corner-case: If builtinClass has a subclass which is also
+ // annotated with @StarlarkBuiltin with the same name, and also has the same
+ // docstring, then the subclass takes precedence.
+ // (This is useful if one class is the "common" one with stable methods, and its subclass is
+ // an experimental class that also supports all stable methods.)
+ Preconditions.checkState(
+ existingPage instanceof StarlarkBuiltinDoc,
+ "the same name %s is assigned to both a global method environment and a builtin type",
+ starlarkBuiltin.name());
+ Class<?> clazz = ((StarlarkBuiltinDoc) existingPage).getClassObject();
+ validateCompatibleBuiltins(clazz, builtinClass);
- if (previousModuleDoc.getClassObject().isAssignableFrom(moduleClass)) {
- // The new module is a subclass of the old module, so use the subclass.
- modules.put(
- moduleAnnotation.name(),
- new StarlarkBuiltinDoc(
- moduleAnnotation, /*title=*/ moduleAnnotation.name(), moduleClass, expander));
- }
- }
+ if (clazz.isAssignableFrom(builtinClass)) {
+ // The new builtin is a subclass of the old builtin, so use the subclass.
+ pagesInCategory.put(
+ starlarkBuiltin.name(), new StarlarkBuiltinDoc(starlarkBuiltin, builtinClass, expander));
}
}
- /**
- * Validate that it is acceptable that the given module classes with the same module name
- * co-exist.
- */
- private static void validateCompatibleModules(Class<?> one, Class<?> two) {
- StarlarkBuiltin moduleOne = one.getAnnotation(StarlarkBuiltin.class);
- StarlarkBuiltin moduleTwo = two.getAnnotation(StarlarkBuiltin.class);
+ /** Validate that it is acceptable that the given builtin classes with the same name co-exist. */
+ private static void validateCompatibleBuiltins(Class<?> one, Class<?> two) {
+ StarlarkBuiltin builtinOne = one.getAnnotation(StarlarkBuiltin.class);
+ StarlarkBuiltin builtinTwo = two.getAnnotation(StarlarkBuiltin.class);
if (one.isAssignableFrom(two) || two.isAssignableFrom(one)) {
- if (!moduleOne.doc().equals(moduleTwo.doc())) {
+ if (!builtinOne.doc().equals(builtinTwo.doc())) {
throw new IllegalStateException(
String.format(
- "%s and %s are related modules but have mismatching documentation for '%s'",
- one, two, moduleOne.name()));
+ "%s and %s are related builtins but have mismatching documentation for '%s'",
+ one, two, builtinOne.name()));
}
} else {
throw new IllegalStateException(
String.format(
- "%s and %s are unrelated modules with documentation for '%s'",
- one, two, moduleOne.name()));
+ "%s and %s are unrelated builtins with documentation for '%s'",
+ one, two, builtinOne.name()));
}
}
- private static void collectModuleMethods(
- Class<?> moduleClass, Map<String, StarlarkBuiltinDoc> modules, StarlarkDocExpander expander) {
- StarlarkBuiltin moduleAnnotation =
- Preconditions.checkNotNull(moduleClass.getAnnotation(StarlarkBuiltin.class));
+ private static void collectBuiltinMethods(
+ Class<?> builtinClass,
+ Map<Category, Map<String, StarlarkDocPage>> pages,
+ StarlarkDocExpander expander) {
+ StarlarkBuiltin starlarkBuiltin = builtinClass.getAnnotation(StarlarkBuiltin.class);
- if (moduleAnnotation.documented()) {
- StarlarkBuiltinDoc moduleDoc =
- Preconditions.checkNotNull(modules.get(moduleAnnotation.name()));
+ if (starlarkBuiltin == null || !starlarkBuiltin.documented()) {
+ return;
+ }
+ StarlarkBuiltinDoc builtinDoc =
+ (StarlarkBuiltinDoc) pages.get(Category.of(starlarkBuiltin)).get(starlarkBuiltin.name());
- if (moduleClass == moduleDoc.getClassObject()) {
- for (Map.Entry<Method, StarlarkMethod> entry :
- Starlark.getMethodAnnotations(moduleClass).entrySet()) {
- // Collect methods that aren't directly constructors (i.e. have the @StarlarkConstructor
- // annotation).
- // Struct fields that return a type that has @StarlarkConstructor are a bit special:
- // they're visited here because they're seen as an attribute of the module, but act more
- // like a reference to the type they construct
- if (!entry.getKey().isAnnotationPresent(StarlarkConstructor.class)) {
- Method javaMethod = entry.getKey();
- StarlarkMethod starlarkMethod = entry.getValue();
- // Handle struct fields that return a Starlark constructor so that
- // documentation can link to the constructed type.
- if (starlarkMethod.structField()) {
- Method constructor = getSelfCallConstructorMethod(javaMethod.getReturnType());
- if (constructor != null) {
- javaMethod = constructor;
- }
- }
- moduleDoc.addMethod(
- new StarlarkJavaMethodDoc(
- moduleDoc.getName(), javaMethod, starlarkMethod, expander));
- }
+ if (builtinClass != builtinDoc.getClassObject()) {
+ return;
+ }
+ for (Map.Entry<Method, StarlarkMethod> entry :
+ Starlark.getMethodAnnotations(builtinClass).entrySet()) {
+ // Collect methods that aren't directly constructors (i.e. have the @StarlarkConstructor
+ // annotation).
+ if (entry.getKey().isAnnotationPresent(StarlarkConstructor.class)) {
+ continue;
+ }
+ Method javaMethod = entry.getKey();
+ StarlarkMethod starlarkMethod = entry.getValue();
+ // Struct fields that return a type that has @StarlarkConstructor are a bit special:
+ // they're visited here because they're seen as an attribute of the module, but act more
+ // like a reference to the type they construct.
+ // TODO(wyv): does this actually happen???
+ if (starlarkMethod.structField()) {
+ Method selfCall =
+ Starlark.getSelfCallMethod(StarlarkSemantics.DEFAULT, javaMethod.getReturnType());
+ if (selfCall != null && selfCall.isAnnotationPresent(StarlarkConstructor.class)) {
+ javaMethod = selfCall;
}
}
+ builtinDoc.addMethod(
+ new StarlarkJavaMethodDoc(builtinDoc.getName(), javaMethod, starlarkMethod, expander));
}
}
- @Nullable
- private static Method getSelfCallConstructorMethod(Class<?> objectClass) {
- Method selfCallMethod = Starlark.getSelfCallMethod(StarlarkSemantics.DEFAULT, objectClass);
- if (selfCallMethod != null && selfCallMethod.isAnnotationPresent(StarlarkConstructor.class)) {
- return selfCallMethod;
- }
- return null;
- }
-
/**
* Adds {@link StarlarkJavaMethodDoc} entries to the top level module, one for
- * each @StarlarkMethod method defined in the given @GlobalMethods class {@code moduleClass}.
+ * each @StarlarkMethod method defined in the given @GlobalMethods class {@code clazz}.
*/
- private static void collectDocumentedMethods(
- Class<?> moduleClass, Map<String, StarlarkBuiltinDoc> modules, StarlarkDocExpander expander) {
- StarlarkBuiltinDoc topLevelModuleDoc = getTopLevelModuleDoc(modules);
+ private static void collectGlobalMethods(
+ Class<?> clazz,
+ Map<Category, Map<String, StarlarkDocPage>> pages,
+ StarlarkDocExpander expander) {
+ GlobalMethods globalMethods = clazz.getAnnotation(GlobalMethods.class);
- for (Map.Entry<Method, StarlarkMethod> entry :
- Starlark.getMethodAnnotations(moduleClass).entrySet()) {
- // Only add non-constructor global library methods. Constructors are added later.
- if (!entry.getKey().isAnnotationPresent(StarlarkConstructor.class)) {
- topLevelModuleDoc.addMethod(
- new StarlarkJavaMethodDoc("", entry.getKey(), entry.getValue(), expander));
+ if (globalMethods == null && !clazz.getName().equals("net.starlark.java.eval.MethodLibrary")) {
+ return;
+ }
+
+ Environment[] environments =
+ globalMethods == null ? new Environment[] {Environment.ALL} : globalMethods.environment();
+ for (Environment environment : environments) {
+ StarlarkDocPage page =
+ pages
+ .get(Category.GLOBAL_FUNCTION)
+ .computeIfAbsent(
+ environment.getTitle(), title -> new StarlarkGlobalsDoc(environment, expander));
+ for (Map.Entry<Method, StarlarkMethod> entry :
+ Starlark.getMethodAnnotations(clazz).entrySet()) {
+ // Only add non-constructor global library methods. Constructors are added later.
+ // TODO(wyv): add a redirect instead
+ if (!entry.getKey().isAnnotationPresent(StarlarkConstructor.class)) {
+ page.addMethod(new StarlarkJavaMethodDoc("", entry.getKey(), entry.getValue(), expander));
+ }
}
}
}
private static void collectConstructor(
- Map<String, StarlarkBuiltinDoc> modules, Method method, StarlarkDocExpander expander) {
- Preconditions.checkNotNull(method.getAnnotation(StarlarkConstructor.class));
+ Map<Category, Map<String, StarlarkDocPage>> pages,
+ Method method,
+ StarlarkDocExpander expander) {
+ if (!method.isAnnotationPresent(StarlarkConstructor.class)) {
+ return;
+ }
- StarlarkBuiltin builtinType = StarlarkAnnotations.getStarlarkBuiltin(method.getReturnType());
- if (builtinType == null || !builtinType.documented()) {
+ StarlarkBuiltin starlarkBuiltin =
+ StarlarkAnnotations.getStarlarkBuiltin(method.getReturnType());
+ if (starlarkBuiltin == null || !starlarkBuiltin.documented()) {
// The class of the constructed object type has no documentation, so no place to add
// constructor information.
return;
}
StarlarkMethod methodAnnot =
Preconditions.checkNotNull(method.getAnnotation(StarlarkMethod.class));
- StarlarkBuiltinDoc doc = modules.get(builtinType.name());
+ StarlarkDocPage doc = pages.get(Category.of(starlarkBuiltin)).get(starlarkBuiltin.name());
doc.setConstructor(
- new StarlarkConstructorMethodDoc(builtinType.name(), method, methodAnnot, expander));
+ new StarlarkConstructorMethodDoc(starlarkBuiltin.name(), method, methodAnnot, expander));
}
/**
@@ -297,16 +284,20 @@
* documentation)
*/
private static void collectConstructorMethods(
- Class<?> moduleClass, Map<String, StarlarkBuiltinDoc> modules, StarlarkDocExpander expander) {
- Method selfCallConstructor = getSelfCallConstructorMethod(moduleClass);
- if (selfCallConstructor != null) {
- collectConstructor(modules, selfCallConstructor, expander);
+ Class<?> clazz,
+ Map<Category, Map<String, StarlarkDocPage>> pages,
+ StarlarkDocExpander expander) {
+ if (!clazz.isAnnotationPresent(StarlarkBuiltin.class)
+ && !clazz.isAnnotationPresent(GlobalMethods.class)) {
+ return;
+ }
+ Method selfCall = Starlark.getSelfCallMethod(StarlarkSemantics.DEFAULT, clazz);
+ if (selfCall != null) {
+ collectConstructor(pages, selfCall, expander);
}
- for (Method method : Starlark.getMethodAnnotations(moduleClass).keySet()) {
- if (method.isAnnotationPresent(StarlarkConstructor.class)) {
- collectConstructor(modules, method, expander);
- }
+ for (Method method : Starlark.getMethodAnnotations(clazz).keySet()) {
+ collectConstructor(pages, method, expander);
}
}
}
diff --git a/src/main/java/com/google/devtools/build/docgen/StarlarkDocumentationProcessor.java b/src/main/java/com/google/devtools/build/docgen/StarlarkDocumentationProcessor.java
index a7ac11d..be8f98f 100644
--- a/src/main/java/com/google/devtools/build/docgen/StarlarkDocumentationProcessor.java
+++ b/src/main/java/com/google/devtools/build/docgen/StarlarkDocumentationProcessor.java
@@ -14,30 +14,22 @@
package com.google.devtools.build.docgen;
import com.google.common.collect.ImmutableList;
+import com.google.common.collect.ImmutableMap;
import com.google.devtools.build.docgen.annot.DocCategory;
-import com.google.devtools.build.docgen.starlark.StarlarkBuiltinDoc;
import com.google.devtools.build.docgen.starlark.StarlarkDocExpander;
-import com.google.devtools.build.docgen.starlark.StarlarkMethodDoc;
+import com.google.devtools.build.docgen.starlark.StarlarkDocPage;
import com.google.devtools.build.lib.util.Classpath.ClassPathException;
import java.io.File;
import java.io.IOException;
-import java.text.Collator;
-import java.util.ArrayList;
-import java.util.Collections;
+import java.nio.file.Files;
+import java.nio.file.Path;
import java.util.HashMap;
-import java.util.LinkedHashMap;
-import java.util.List;
-import java.util.Locale;
import java.util.Map;
-import java.util.TreeMap;
import net.starlark.java.annot.StarlarkBuiltin;
/** A class to assemble documentation for Starlark. */
public final class StarlarkDocumentationProcessor {
- private static final ImmutableList<Category> GLOBAL_CATEGORIES =
- ImmutableList.of(Category.TOP_LEVEL_MODULE);
-
private StarlarkDocumentationProcessor() {}
/** Generates the Starlark documentation to the given output directory. */
@@ -59,152 +51,63 @@
StarlarkDocExpander expander =
new StarlarkDocExpander(new RuleLinkExpander(/* singlePage= */ false, linkMap));
- Map<String, StarlarkBuiltinDoc> modules =
- new TreeMap<>(StarlarkDocumentationCollector.getAllModules(expander));
+ ImmutableMap<Category, ImmutableList<StarlarkDocPage>> allPages =
+ StarlarkDocumentationCollector.getAllDocPages(expander);
- // Generate the top level module first in the doc
- StarlarkBuiltinDoc topLevelModule =
- modules.remove(StarlarkDocumentationCollector.getTopLevelModule().name());
- writePage(outputDir, topLevelModule);
-
- // Use a LinkedHashMap to preserve ordering of categories, as the output iterates over
- // this map's entry set to determine category ordering.
- Map<Category, List<StarlarkBuiltinDoc>> modulesByCategory = new LinkedHashMap<>();
- for (Category c : Category.values()) {
- modulesByCategory.put(c, new ArrayList<StarlarkBuiltinDoc>());
- }
-
- modulesByCategory.get(Category.of(topLevelModule.getAnnotation())).add(topLevelModule);
-
- for (StarlarkBuiltinDoc module : modules.values()) {
- if (module.getAnnotation().documented()) {
- writePage(outputDir, module);
- modulesByCategory.get(Category.of(module.getAnnotation())).add(module);
- }
- }
- Collator us = Collator.getInstance(Locale.US);
- for (List<StarlarkBuiltinDoc> module : modulesByCategory.values()) {
- Collections.sort(module, (doc1, doc2) -> us.compare(doc1.getTitle(), doc2.getTitle()));
- }
- writeCategoryPage(Category.CORE, outputDir, modulesByCategory, expander);
- writeCategoryPage(Category.CONFIGURATION_FRAGMENT, outputDir, modulesByCategory, expander);
- writeCategoryPage(Category.BUILTIN, outputDir, modulesByCategory, expander);
- writeCategoryPage(Category.PROVIDER, outputDir, modulesByCategory, expander);
- writeNavPage(outputDir, modulesByCategory.get(Category.TOP_LEVEL_MODULE));
-
- // In the code, there are two StarlarkModuleCategory instances that have no heading:
- // TOP_LEVEL_TYPE and NONE.
-
- // TOP_LEVEL_TYPE also contains the "global" module.
- // We remove both categories and the "global" module from the map and display them manually:
- // - Methods in the "global" module are displayed under "Global Methods and Constants".
- // - Modules in both categories are displayed under "Global Modules" (except for the global
- // module itself).
- List<String> globalFunctions = new ArrayList<>();
- List<String> globalConstants = new ArrayList<>();
- StarlarkBuiltinDoc globalModule = findGlobalModule(modulesByCategory);
- for (StarlarkMethodDoc method : globalModule.getMethods()) {
- if (method.documented()) {
- if (method.isCallable()) {
- globalFunctions.add(method.getName());
- } else {
- globalConstants.add(method.getName());
- }
+ for (var categoryAndPages : allPages.entrySet()) {
+ writeCategoryPage(
+ categoryAndPages.getKey(), outputDir, categoryAndPages.getValue(), expander);
+ for (StarlarkDocPage page : categoryAndPages.getValue()) {
+ writePage(outputDir, categoryAndPages.getKey(), page);
}
}
- List<StarlarkBuiltinDoc> globalModules = new ArrayList<>();
- for (Category globalCategory : GLOBAL_CATEGORIES) {
- for (StarlarkBuiltinDoc module : modulesByCategory.remove(globalCategory)) {
- if (!module.getName().equals(globalModule.getName())) {
- globalModules.add(module);
- }
- }
- }
-
- Collections.sort(globalModules, (doc1, doc2) -> us.compare(doc1.getName(), doc2.getName()));
- writeOverviewPage(
- outputDir,
- globalModule.getName(),
- globalFunctions,
- globalConstants,
- globalModules,
- modulesByCategory);
+ writeOverviewPage(outputDir, allPages);
if (shouldCreateToc(options)) {
- writeTableOfContents(outputDir, globalModules, modulesByCategory);
+ writeTableOfContents(outputDir, allPages);
}
}
- private static StarlarkBuiltinDoc findGlobalModule(
- Map<Category, List<StarlarkBuiltinDoc>> modulesByCategory) {
- List<StarlarkBuiltinDoc> topLevelModules = modulesByCategory.get(Category.TOP_LEVEL_MODULE);
- String globalModuleName = StarlarkDocumentationCollector.getTopLevelModule().name();
- for (StarlarkBuiltinDoc module : topLevelModules) {
- if (module.getName().equals(globalModuleName)) {
- return module;
- }
- }
-
- throw new IllegalStateException("No globals module in the top level category.");
- }
-
- private static void writePage(String outputDir, StarlarkBuiltinDoc module) throws IOException {
- File starlarkDocPath = new File(outputDir + "/" + module.getName() + ".html");
+ private static void writePage(String outputDir, Category category, StarlarkDocPage docPage)
+ throws IOException {
+ File starlarkDocPath =
+ new File(String.format("%s/%s/%s.html", outputDir, category.getPath(), docPage.getName()));
Page page = TemplateEngine.newPage(DocgenConsts.STARLARK_LIBRARY_TEMPLATE);
- page.add("module", module);
+ page.add("page", docPage);
page.write(starlarkDocPath);
}
private static void writeCategoryPage(
Category category,
String outputDir,
- Map<Category, List<StarlarkBuiltinDoc>> modules,
+ ImmutableList<StarlarkDocPage> allPages,
StarlarkDocExpander expander)
throws IOException {
- File starlarkDocPath =
- new File(String.format("%s/starlark-%s.html", outputDir, category.getTemplateIdentifier()));
+ Files.createDirectories(Path.of(outputDir, category.getPath()));
+
+ File starlarkDocPath = new File(String.format("%s/%s.html", outputDir, category.getPath()));
Page page = TemplateEngine.newPage(DocgenConsts.STARLARK_MODULE_CATEGORY_TEMPLATE);
page.add("category", category);
- page.add("modules", modules.get(category));
+ page.add("allPages", allPages);
page.add("description", expander.expand(category.description));
page.write(starlarkDocPath);
}
- private static void writeNavPage(String outputDir, List<StarlarkBuiltinDoc> navModules)
- throws IOException {
- File navFile = new File(outputDir + "/starlark-nav.html");
- Page page = TemplateEngine.newPage(DocgenConsts.STARLARK_NAV_TEMPLATE);
- page.add("modules", navModules);
- page.write(navFile);
- }
-
private static void writeOverviewPage(
- String outputDir,
- String globalModuleName,
- List<String> globalFunctions,
- List<String> globalConstants,
- List<StarlarkBuiltinDoc> globalModules,
- Map<Category, List<StarlarkBuiltinDoc>> modulesPerCategory)
+ String outputDir, ImmutableMap<Category, ImmutableList<StarlarkDocPage>> allPages)
throws IOException {
- File starlarkDocPath = new File(outputDir + "/starlark-overview.html");
+ File starlarkDocPath = new File(outputDir + "/overview.html");
Page page = TemplateEngine.newPage(DocgenConsts.STARLARK_OVERVIEW_TEMPLATE);
- page.add("global_name", globalModuleName);
- page.add("global_functions", globalFunctions);
- page.add("global_constants", globalConstants);
- page.add("global_modules", globalModules);
- page.add("modules", modulesPerCategory);
+ page.add("allPages", allPages);
page.write(starlarkDocPath);
}
private static void writeTableOfContents(
- String outputDir,
- List<StarlarkBuiltinDoc> globalModules,
- Map<Category, List<StarlarkBuiltinDoc>> modulesPerCategory)
+ String outputDir, ImmutableMap<Category, ImmutableList<StarlarkDocPage>> allPages)
throws IOException {
File starlarkDocPath = new File(outputDir + "/_toc.yaml");
Page page = TemplateEngine.newPage(DocgenConsts.STARLARK_TOC_TEMPLATE);
- page.add("global_modules", globalModules);
- page.add("modules", modulesPerCategory);
+ page.add("allPages", allPages);
page.write(starlarkDocPath);
}
@@ -232,37 +135,56 @@
* accessed by templates, using reflection.
*/
public enum Category {
+ GLOBAL_FUNCTION(
+ "Global functions",
+ "globals",
+ "This section lists the global functions available in Starlark. The list of available"
+ + " functions differs depending on the file type (whether a BUILD file, or a .bzl file,"
+ + " etc)."),
+
CONFIGURATION_FRAGMENT(
"Configuration Fragments",
+ "fragments",
"Configuration fragments give rules access to "
- + "language-specific parts of <a href=\"configuration.html\">"
+ + "language-specific parts of <a href=\"builtins/configuration.html\">"
+ "configuration</a>. "
+ "<p>Rule implementations can get them using "
- + "<code><a href=\"ctx.html#fragments\">ctx."
+ + "<code><a href=\"builtins/ctx.html#fragments\">ctx."
+ "fragments</a>.<i>[fragment name]</i></code>"),
PROVIDER(
"Providers",
+ "providers",
"This section lists providers available on built-in rules. See the <a"
+ " href='https://bazel.build/extending/rules#providers'>Rules page</a> for more on"
- + " providers."),
+ + " providers. These symbols are available only in .bzl files."),
- BUILTIN("Built-in Types", "This section lists types of Starlark objects."),
+ BUILTIN(
+ "Built-in Types",
+ "builtins",
+ "This section lists types of Starlark objects. With some exceptions, these type names are"
+ + " not valid Starlark symbols; instances of them may be acquired through different"
+ + " means."),
// Used for top-level modules of functions in the global namespace. Such modules will always
// be usable solely by accessing their members, via modulename.funcname() or
// modulename.constantname.
// Examples: attr, cc_common, config, java_common
- TOP_LEVEL_MODULE(null, null),
+ TOP_LEVEL_MODULE(
+ "Top-level Modules",
+ "toplevel",
+ "This section lists top-level modules. These symbols are available only in .bzl files."),
CORE(
"Core Starlark data types",
+ "core",
"This section lists the data types of the <a"
+ " href='https://github.com/bazelbuild/starlark/blob/master/spec.md#built-in-constants-and-functions'>Starlark"
- + " core language</a>.");
+ + " core language</a>. With some exceptions, these type names are not valid Starlark"
+ + " symbols; instances of them may be acquired through different means.");
// Maps (essentially free-form) strings in annotations to permitted categories.
- static Category of(StarlarkBuiltin annot) {
+ public static Category of(StarlarkBuiltin annot) {
switch (annot.category()) {
case DocCategory.CONFIGURATION_FRAGMENT:
return CONFIGURATION_FRAGMENT;
@@ -283,12 +205,14 @@
}
}
- private Category(String title, String description) {
+ Category(String title, String path, String description) {
this.title = title;
+ this.path = path;
this.description = description;
}
private final String title;
+ private final String path;
private final String description;
public String getTitle() {
@@ -299,8 +223,8 @@
return description;
}
- public String getTemplateIdentifier() {
- return name().toLowerCase().replace("_", "-");
+ public String getPath() {
+ return path;
}
}
}
diff --git a/src/main/java/com/google/devtools/build/docgen/SymbolFamilies.java b/src/main/java/com/google/devtools/build/docgen/SymbolFamilies.java
index 38e9bec..d7f99da 100644
--- a/src/main/java/com/google/devtools/build/docgen/SymbolFamilies.java
+++ b/src/main/java/com/google/devtools/build/docgen/SymbolFamilies.java
@@ -15,8 +15,9 @@
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;
-import com.google.devtools.build.docgen.starlark.StarlarkBuiltinDoc;
+import com.google.devtools.build.docgen.StarlarkDocumentationProcessor.Category;
import com.google.devtools.build.docgen.starlark.StarlarkDocExpander;
+import com.google.devtools.build.docgen.starlark.StarlarkDocPage;
import com.google.devtools.build.lib.analysis.ConfiguredRuleClassProvider;
import com.google.devtools.build.lib.util.Classpath.ClassPathException;
import com.google.devtools.build.skydoc.fakebuildapi.FakeStarlarkNativeModuleApi;
@@ -33,7 +34,7 @@
*/
public class SymbolFamilies {
private final ImmutableList<RuleDocumentation> nativeRules;
- private final ImmutableMap<String, StarlarkBuiltinDoc> types;
+ private final ImmutableMap<Category, ImmutableList<StarlarkDocPage>> allDocPages;
// Mappings between Starlark names and Starlark entities generated from the fakebuildapi.
private final ImmutableMap<String, Object> globals;
@@ -51,7 +52,7 @@
expander.ruleExpander, configuredRuleClassProvider, inputDirs, denyList));
this.globals = Starlark.UNIVERSE;
this.bzlGlobals = collectBzlGlobals(configuredRuleClassProvider);
- this.types = StarlarkDocumentationCollector.getAllModules(expander);
+ this.allDocPages = StarlarkDocumentationCollector.getAllDocPages(expander);
}
/*
@@ -78,8 +79,8 @@
}
// Returns a mapping between type names and module/type documentation.
- public Map<String, StarlarkBuiltinDoc> getTypes() {
- return types;
+ public ImmutableMap<Category, ImmutableList<StarlarkDocPage>> getAllDocPages() {
+ return allDocPages;
}
/*
diff --git a/src/main/java/com/google/devtools/build/docgen/annot/GlobalMethods.java b/src/main/java/com/google/devtools/build/docgen/annot/GlobalMethods.java
index c941ad7..d6f382f 100644
--- a/src/main/java/com/google/devtools/build/docgen/annot/GlobalMethods.java
+++ b/src/main/java/com/google/devtools/build/docgen/annot/GlobalMethods.java
@@ -29,22 +29,36 @@
public @interface GlobalMethods {
/** The environment in which the global methods in the annotated class are available. */
enum Environment {
- BUILD("BUILD files"),
- WORKSPACE("WORKSPACE files"),
- MODULE("MODULE.bazel files"),
- BZL(".bzl files"),
- ALL("All Starlark files");
+ BUILD(
+ "BUILD files",
+ "This page contains global methods available in BUILD files. See also the Build"
+ + " Encyclopedia for extra <a href=\"${link functions}\">functions</a> and build rules,"
+ + " which can also be used in BUILD files."),
+ WORKSPACE("WORKSPACE files", "This page contains global methods available in WORKSPACE files."),
+ MODULE(
+ "MODULE.bazel files", "This page contains global methods available in MODULE.bazel files."),
+ BZL(".bzl files", "This page contains global methods available in all .bzl files."),
+ ALL(
+ "All Starlark files",
+ "This page contains global methods available in all Starlark files, including BUILD,"
+ + " WORKSPACE, MODULE.bazel, and all .bzl files.");
private final String title;
+ private final String description;
- Environment(String title) {
+ Environment(String title, String description) {
this.title = title;
+ this.description = description;
}
public String getTitle() {
return title;
}
+ public String getDescription() {
+ return description;
+ }
+
public String getPath() {
return Ascii.toLowerCase(name());
}
diff --git a/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkBuiltinDoc.java b/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkBuiltinDoc.java
index 74a9738..c83bf9b 100644
--- a/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkBuiltinDoc.java
+++ b/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkBuiltinDoc.java
@@ -1,4 +1,4 @@
-// Copyright 2014 The Bazel Authors. All rights reserved.
+// 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.
@@ -11,155 +11,46 @@
// 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.
+
package com.google.devtools.build.docgen.starlark;
-import com.google.common.base.Preconditions;
-import com.google.common.collect.HashMultimap;
-import com.google.common.collect.ImmutableCollection;
-import com.google.common.collect.ImmutableList;
-import com.google.common.collect.ImmutableSortedSet;
-import com.google.common.collect.Iterables;
-import com.google.common.collect.Multimap;
-import java.text.Collator;
-import java.util.Collection;
-import java.util.Comparator;
-import java.util.Locale;
-import java.util.TreeMap;
-import javax.annotation.Nullable;
import net.starlark.java.annot.StarlarkBuiltin;
-import net.starlark.java.annot.StarlarkMethod;
-/**
- * A class representing documentation for a Starlark built-in object with its {@link StarlarkModule}
- * annotation and with the {@link StarlarkMethod} methods it documents.
- */
-public final class StarlarkBuiltinDoc extends StarlarkDoc {
- private final StarlarkBuiltin module;
- private final String title;
- private final Class<?> classObject;
- private final Multimap<String, StarlarkJavaMethodDoc> javaMethods;
- private TreeMap<String, StarlarkMethodDoc> methodMap;
- @Nullable private StarlarkConstructorMethodDoc javaConstructor;
- private final boolean isTopLevel;
-
+/** A documentation page for a Starlark builtin type. */
+public final class StarlarkBuiltinDoc extends StarlarkDocPage {
private static final String SOURCE_ROOT = "src/main/java";
- private static final String NO_SOURCE_FILE_VALUE = "NONE";
+
+ private final StarlarkBuiltin starlarkBuiltin;
+ private final Class<?> classObject;
public StarlarkBuiltinDoc(
- StarlarkBuiltin module, String title, Class<?> classObject, StarlarkDocExpander expander) {
- this(module, title, classObject, expander, false);
- }
-
- public StarlarkBuiltinDoc(
- StarlarkBuiltin module,
- String title,
- Class<?> classObject,
- StarlarkDocExpander expander,
- boolean isTopLevel) {
+ StarlarkBuiltin starlarkBuiltin, Class<?> classObject, StarlarkDocExpander expander) {
super(expander);
- this.module =
- Preconditions.checkNotNull(
- module, "Class has to be annotated with StarlarkBuiltin: %s", classObject);
- this.title = title;
+ this.starlarkBuiltin = starlarkBuiltin;
this.classObject = classObject;
- this.methodMap = new TreeMap<>(Collator.getInstance(Locale.US));
- this.javaMethods = HashMultimap.<String, StarlarkJavaMethodDoc>create();
- this.isTopLevel = isTopLevel;
}
@Override
public String getName() {
- return module.name();
+ return starlarkBuiltin.name();
}
@Override
public String getRawDocumentation() {
- return module.doc();
+ return starlarkBuiltin.doc();
}
+ @Override
public String getTitle() {
- return title;
- }
-
- public StarlarkBuiltin getAnnotation() {
- return module;
+ return starlarkBuiltin.name();
}
public Class<?> getClassObject() {
return classObject;
}
- public void setConstructor(StarlarkConstructorMethodDoc method) {
- Preconditions.checkState(
- javaConstructor == null,
- "Constructor method doc already set for %s:\n existing: %s\n attempted: %s",
- getName(),
- javaConstructor,
- method);
- javaConstructor = method;
- }
-
- public void addMethod(StarlarkJavaMethodDoc method) {
- if (!method.documented()) {
- return;
- }
-
- String shortName = method.getName();
- Collection<StarlarkJavaMethodDoc> overloads = javaMethods.get(shortName);
- if (!overloads.isEmpty()) {
- method.setOverloaded(true);
- // Overload information only needs to be updated if we're discovering the first overload
- // (= the second method of the same name).
- if (overloads.size() == 1) {
- Iterables.getOnlyElement(overloads).setOverloaded(true);
- }
- }
- javaMethods.put(shortName, method);
-
- // If the method is overloaded, getName() now returns a longer,
- // unique name including the names of the parameters.
- StarlarkMethodDoc prev = methodMap.put(method.getName(), method);
- if (prev != null && !prev.getMethod().equals(method.getMethod())) {
- throw new IllegalStateException(
- String.format(
- "Starlark type '%s' (%s) has distinct overloads of %s: %s, %s",
- module.name(), classObject, method.getName(), method.getMethod(), prev.getMethod()));
- }
- }
-
- public boolean javaMethodsNotCollected() {
- return javaMethods.isEmpty();
- }
-
- public Collection<StarlarkMethodDoc> getJavaMethods() {
- ImmutableSortedSet.Builder<StarlarkMethodDoc> methods =
- new ImmutableSortedSet.Builder<>(Comparator.comparing(StarlarkMethodDoc::getName));
-
- if (javaConstructor != null) {
- methods.add(javaConstructor);
- }
- methods.addAll(javaMethods.values());
- return methods.build();
- }
-
- public ImmutableCollection<? extends StarlarkMethodDoc> getMethods() {
- ImmutableList.Builder<StarlarkMethodDoc> methods = ImmutableList.builder();
- if (javaConstructor != null) {
- methods.add(javaConstructor);
- }
- return methods.addAll(methodMap.values()).build();
- }
-
- @Nullable
- public StarlarkConstructorMethodDoc getConstructor() {
- return javaConstructor;
- }
-
+ @Override
public String getSourceFile() {
- if (isTopLevel) {
- return NO_SOURCE_FILE_VALUE;
- }
-
String[] parts = classObject.getName().split("\\$", -1);
return String.format("%s/%s.java", SOURCE_ROOT, parts[0].replace('.', '/'));
}
diff --git a/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkDoc.java b/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkDoc.java
index 582a0da..86e29f4 100644
--- a/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkDoc.java
+++ b/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkDoc.java
@@ -14,6 +14,7 @@
package com.google.devtools.build.docgen.starlark;
import com.google.common.collect.ImmutableList;
+import com.google.devtools.build.docgen.StarlarkDocumentationProcessor.Category;
import com.google.devtools.build.lib.collect.nestedset.NestedSet;
import java.lang.reflect.Method;
import java.util.Arrays;
@@ -29,9 +30,7 @@
import net.starlark.java.eval.Tuple;
/** Abstract class for containing documentation for a Starlark syntactic entity. */
-abstract class StarlarkDoc {
- protected static final String TOP_LEVEL_ID = "globals";
-
+public abstract class StarlarkDoc {
private final StarlarkDocExpander expander;
protected StarlarkDoc(StarlarkDocExpander expander) {
@@ -63,28 +62,29 @@
protected String getTypeAnchor(Class<?> type) {
if (type.equals(Boolean.class) || type.equals(boolean.class)) {
- return "<a class=\"anchor\" href=\"bool.html\">bool</a>";
+ return "<a class=\"anchor\" href=\"../core/bool.html\">bool</a>";
} else if (type.equals(int.class) || type.equals(Integer.class)) {
- return "<a class=\"anchor\" href=\"int.html\">int</a>";
+ return "<a class=\"anchor\" href=\"../core/int.html\">int</a>";
} else if (type.equals(String.class)) {
- return "<a class=\"anchor\" href=\"string.html\">string</a>";
+ return "<a class=\"anchor\" href=\"../core/string.html\">string</a>";
} else if (Map.class.isAssignableFrom(type)) {
- return "<a class=\"anchor\" href=\"dict.html\">dict</a>";
+ return "<a class=\"anchor\" href=\"../core/dict.html\">dict</a>";
} else if (type.equals(Tuple.class)) {
- return "<a class=\"anchor\" href=\"tuple.html\">tuple</a>";
+ return "<a class=\"anchor\" href=\"../core/tuple.html\">tuple</a>";
} else if (type.equals(StarlarkList.class) || type.equals(ImmutableList.class)) {
- return "<a class=\"anchor\" href=\"list.html\">list</a>";
+ return "<a class=\"anchor\" href=\"../core/list.html\">list</a>";
} else if (type.equals(Sequence.class)) {
- return "<a class=\"anchor\" href=\"list.html\">sequence</a>";
+ return "<a class=\"anchor\" href=\"../core/list.html\">sequence</a>";
} else if (type.equals(Void.TYPE) || type.equals(NoneType.class)) {
- return "<a class=\"anchor\" href=\"" + TOP_LEVEL_ID + ".html#None\">None</a>";
+ return "None";
} else if (type.equals(NestedSet.class)) {
- return "<a class=\"anchor\" href=\"depset.html\">depset</a>";
+ return "<a class=\"anchor\" href=\"../builtins/depset.html\">depset</a>";
} else if (StarlarkAnnotations.getStarlarkBuiltin(type) != null) {
- StarlarkBuiltin module = StarlarkAnnotations.getStarlarkBuiltin(type);
- if (module.documented()) {
- return String.format("<a class=\"anchor\" href=\"%1$s.html\">%1$s</a>",
- module.name());
+ StarlarkBuiltin starlarkBuiltin = StarlarkAnnotations.getStarlarkBuiltin(type);
+ if (starlarkBuiltin.documented()) {
+ return String.format(
+ "<a class=\"anchor\" href=\"../%1$s/%2$s.html\">%2$s</a>",
+ Category.of(starlarkBuiltin).getPath(), starlarkBuiltin.name());
}
}
return Starlark.classType(type);
diff --git a/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkDocPage.java b/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkDocPage.java
new file mode 100644
index 0000000..bb4a875
--- /dev/null
+++ b/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkDocPage.java
@@ -0,0 +1,111 @@
+// 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.
+package com.google.devtools.build.docgen.starlark;
+
+import com.google.common.base.Preconditions;
+import com.google.common.collect.HashMultimap;
+import com.google.common.collect.ImmutableCollection;
+import com.google.common.collect.ImmutableList;
+import com.google.common.collect.ImmutableSortedSet;
+import com.google.common.collect.Iterables;
+import com.google.common.collect.Multimap;
+import java.text.Collator;
+import java.util.Collection;
+import java.util.Comparator;
+import java.util.Locale;
+import java.util.TreeMap;
+import javax.annotation.Nullable;
+
+/**
+ * A typical Starlark documentation page, containing a bunch of field/method documentation entries.
+ */
+public abstract class StarlarkDocPage extends StarlarkDoc {
+ private final Multimap<String, StarlarkJavaMethodDoc> javaMethods;
+ private final TreeMap<String, StarlarkMethodDoc> methodMap;
+ @Nullable private StarlarkConstructorMethodDoc javaConstructor;
+
+ protected StarlarkDocPage(StarlarkDocExpander expander) {
+ super(expander);
+ this.methodMap = new TreeMap<>(Collator.getInstance(Locale.US));
+ this.javaMethods = HashMultimap.create();
+ }
+
+ public abstract String getTitle();
+
+ public void setConstructor(StarlarkConstructorMethodDoc method) {
+ Preconditions.checkState(
+ javaConstructor == null,
+ "Constructor method doc already set for %s:\n existing: %s\n attempted: %s",
+ getName(),
+ javaConstructor,
+ method);
+ javaConstructor = method;
+ }
+
+ public void addMethod(StarlarkJavaMethodDoc method) {
+ if (!method.documented()) {
+ return;
+ }
+
+ String shortName = method.getName();
+ Collection<StarlarkJavaMethodDoc> overloads = javaMethods.get(shortName);
+ if (!overloads.isEmpty()) {
+ method.setOverloaded(true);
+ // Overload information only needs to be updated if we're discovering the first overload
+ // (= the second method of the same name).
+ if (overloads.size() == 1) {
+ Iterables.getOnlyElement(overloads).setOverloaded(true);
+ }
+ }
+ javaMethods.put(shortName, method);
+
+ // If the method is overloaded, getName() now returns a longer,
+ // unique name including the names of the parameters.
+ StarlarkMethodDoc prev = methodMap.put(method.getName(), method);
+ if (prev != null && !prev.getMethod().equals(method.getMethod())) {
+ throw new IllegalStateException(
+ String.format(
+ "Starlark type '%s' has distinct overloads of %s: %s, %s",
+ getName(), method.getName(), method.getMethod(), prev.getMethod()));
+ }
+ }
+
+ public Collection<StarlarkMethodDoc> getJavaMethods() {
+ ImmutableSortedSet.Builder<StarlarkMethodDoc> methods =
+ new ImmutableSortedSet.Builder<>(Comparator.comparing(StarlarkMethodDoc::getName));
+
+ if (javaConstructor != null) {
+ methods.add(javaConstructor);
+ }
+ methods.addAll(javaMethods.values());
+ return methods.build();
+ }
+
+ public ImmutableCollection<? extends StarlarkMethodDoc> getMethods() {
+ ImmutableList.Builder<StarlarkMethodDoc> methods = ImmutableList.builder();
+ if (javaConstructor != null) {
+ methods.add(javaConstructor);
+ }
+ return methods.addAll(methodMap.values()).build();
+ }
+
+ @Nullable
+ public StarlarkConstructorMethodDoc getConstructor() {
+ return javaConstructor;
+ }
+
+ /** Returns the path to the source file backing this doc page. */
+ // This method may seem unused, but it's actually used in the template file (starlark-library.vm).
+ public abstract String getSourceFile();
+}
diff --git a/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkGlobalsDoc.java b/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkGlobalsDoc.java
new file mode 100644
index 0000000..1166af0
--- /dev/null
+++ b/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkGlobalsDoc.java
@@ -0,0 +1,47 @@
+// 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.
+
+package com.google.devtools.build.docgen.starlark;
+
+import com.google.devtools.build.docgen.annot.GlobalMethods.Environment;
+
+/** A documentation page for a list of Starlark global methods in the same environment. */
+public final class StarlarkGlobalsDoc extends StarlarkDocPage {
+ private final Environment environment;
+
+ public StarlarkGlobalsDoc(Environment environment, StarlarkDocExpander expander) {
+ super(expander);
+ this.environment = environment;
+ }
+
+ @Override
+ public String getName() {
+ return environment.getPath();
+ }
+
+ @Override
+ public String getRawDocumentation() {
+ return environment.getDescription();
+ }
+
+ @Override
+ public String getTitle() {
+ return environment.getTitle();
+ }
+
+ @Override
+ public String getSourceFile() {
+ return "NONE";
+ }
+}
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/env.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/env.html
index 9eefe24..8c448aa 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/env.html
+++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/env.html
@@ -17,7 +17,7 @@
Starlark-defined test rules. For your own Starlark rules, you can add an "env"
attribute and use it to populate a
- <a href="/rules/lib/testing#TestEnvironment">TestEnvironment</a>
+ <a href="/rules/lib/toplevel/testing#TestEnvironment">TestEnvironment</a>
Provider.
</p>
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/be/overview.vm b/src/main/java/com/google/devtools/build/docgen/templates/be/overview.vm
index fe0e48d..d05d3c7 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/be/overview.vm
+++ b/src/main/java/com/google/devtools/build/docgen/templates/be/overview.vm
@@ -43,7 +43,7 @@
<li><a href="$expander.expandRef("exports_files")">exports_files</a></li>
<li><a href="$expander.expandRef("glob")">glob</a></li>
<li><a href="$expander.expandRef("select")">select</a></li>
- <li><a href="/rules/lib/globals#workspace">workspace</a></li>
+ <li><a href="/rules/lib/globals/workspace#workspace">workspace</a></li>
</ul>
<h2>Rules</h2>
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/starlark-category.vm b/src/main/java/com/google/devtools/build/docgen/templates/starlark-category.vm
index 1ee5f68..13a9827 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/starlark-category.vm
+++ b/src/main/java/com/google/devtools/build/docgen/templates/starlark-category.vm
@@ -11,9 +11,9 @@
${description}
<ul>
-#foreach ($module in $modules)
+#foreach ($page in $allPages)
-<li><a href="/rules/lib/${module.name}">${module.title}</a></li>
+<li><a href="/rules/lib/${category.path}/${page.name}">${page.title}</a></li>
#end
</ul>
</body>
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/starlark-library.vm b/src/main/java/com/google/devtools/build/docgen/templates/starlark-library.vm
index 3e0b977..efd62a3 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/starlark-library.vm
+++ b/src/main/java/com/google/devtools/build/docgen/templates/starlark-library.vm
@@ -5,18 +5,18 @@
</head>
<body>
-<h1 class="page-title" id="modules.${module.name}">${module.title}</h1>
+<h1 class="page-title" id="modules.${page.name}">${page.title}</h1>
-{% dynamic setvar source_file "${module.sourceFile}" %}
+{% dynamic setvar source_file "${page.sourceFile}" %}
{% include "_buttons.html" %}
<!-- {% raw %} -->
-${module.documentation}
+${page.documentation}
-#if (!$module.methods.isEmpty())
+#if (!$page.methods.isEmpty())
<h2>Members</h2>
<ul>
-#foreach ($method in $module.methods)
+#foreach ($method in $page.methods)
#if ($method.documented())
<li>
<a href="#${method.name}">${method.name}</a>
@@ -26,7 +26,7 @@
</ul>
#end
-#foreach ($method in $module.methods)
+#foreach ($method in $page.methods)
#if ($method.documented())
<h2 id="${method.name}">${method.name}</h2>
#if (!$method.signature.isEmpty())
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/starlark-nav.vm b/src/main/java/com/google/devtools/build/docgen/templates/starlark-nav.vm
deleted file mode 100644
index eb38829..0000000
--- a/src/main/java/com/google/devtools/build/docgen/templates/starlark-nav.vm
+++ /dev/null
@@ -1,5 +0,0 @@
-<li><a href="/rules/lib/globals">Globals</a></li>
-<li><a href="/rules/lib/starlark-builtin">Builtin Types and Modules</a></li>
-<li><a href="/rules/lib/starlark-configuration-fragment">Configuration fragments</a></li>
-<li><a href="/rules/lib/starlark-provider">Providers</a></li>
-<li><a href="/rules/lib/starlark-overview">One-Page Overview</a></li>
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/starlark-overview.vm b/src/main/java/com/google/devtools/build/docgen/templates/starlark-overview.vm
index efdb298..6708e4f 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/starlark-overview.vm
+++ b/src/main/java/com/google/devtools/build/docgen/templates/starlark-overview.vm
@@ -8,84 +8,21 @@
{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/starlark-overview.vm" %}
{% include "_buttons.html" %}
-A list of all modules and globals that are available:
-
+#foreach ($entry in $allPages.entrySet())
<h2>
- <a href="/rules/lib/${global_name}">Global Functions</a>
+ <a href="/rules/lib/${entry.key.path}">${entry.key.title}</a>
</h2>
<ul>
-
-#foreach ($name in $global_functions)
+#foreach ($page in $entry.value)
<li>
- <a href="/rules/lib/${global_name}#${name}">${name}</a>
-
-
- </li>
-
-#end
-
-</ul>
-<h2>
-
-
- <a href="/rules/lib/${global_name}">Global Constants</a>
-
-
-</h2>
-<ul>
-
-#foreach ($name in $global_constants)
-
- <li>
-
-
- <a href="/rules/lib/${global_name}#${name}">${name}</a>
-
-
- </li>
-
-#end
-
-</ul>
-<h2>
- Global Modules
-</h2>
-<ul>
-
-#foreach ($module in $global_modules)
-
- <li>
-
-
- <a href="/rules/lib/${module.name}">${module.name}</a>
-
- </li>
-
-#end
-
-</ul>
-#foreach ($entry in $modules.entrySet())
-<h2>
-
-
- <a href="/rules/lib/starlark-${entry.key.templateIdentifier}">${entry.key.title}</a>
-
-
-</h2>
-<ul>
-#foreach ($module in $entry.value)
-
- <li>
-
-
- <a href="/rules/lib/${module.name}">${module.title}</a>
+ <a href="/rules/lib/${entry.key.path}/${page.name}">${page.title}</a>
</li>
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/starlark-toc.vm b/src/main/java/com/google/devtools/build/docgen/templates/starlark-toc.vm
index 2c8de9f..2358db0 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/starlark-toc.vm
+++ b/src/main/java/com/google/devtools/build/docgen/templates/starlark-toc.vm
@@ -2,23 +2,15 @@
- title: Build API
section:
- title: Overview
- path: /rules/lib/starlark-overview
- - title: "Functions & Constants"
- path: /rules/lib/globals
- - title: Modules
- section:
-#foreach ($module in $global_modules)
- - title: ${module.name}
- path: /rules/lib/${module.name}
-#end
-#foreach ($entry in $modules.entrySet())
+ path: /rules/lib/overview
+#foreach ($entry in $allPages.entrySet())
- title: "${entry.key.title}"
section:
- title: Overview
- path: /rules/lib/starlark-${entry.key.templateIdentifier}
-#foreach ($module in $entry.value)
- - title: ${module.title}
- path: /rules/lib/${module.name}
+ path: /rules/lib/${entry.key.path}
+#foreach ($page in $entry.value)
+ - title: ${page.title}
+ path: /rules/lib/${entry.key.path}/${page.name}
#end
#end
- title: "Repository rules"
diff --git a/src/main/java/com/google/devtools/build/lib/BUILD b/src/main/java/com/google/devtools/build/lib/BUILD
index 39c404d..1f7a2ff 100644
--- a/src/main/java/com/google/devtools/build/lib/BUILD
+++ b/src/main/java/com/google/devtools/build/lib/BUILD
@@ -551,7 +551,10 @@
" $(@D)/skylark-lib" +
" --link_map_path=$(location //src/main/java/com/google/devtools/build/docgen:bazel_link_map)" +
" --create_toc=true" +
- " && zip -qj $@ $(@D)/skylark-lib/*",
+ " && OUTPUT=$$PWD/$@" +
+ " && pushd $(@D)/skylark-lib" +
+ " && zip -qr $$OUTPUT ." +
+ " && popd",
tools = ["//src/main/java/com/google/devtools/build/docgen:skydoc_bin"],
visibility = ["//site:__pkg__"],
)
diff --git a/src/main/java/com/google/devtools/build/lib/analysis/starlark/StarlarkRuleClassFunctions.java b/src/main/java/com/google/devtools/build/lib/analysis/starlark/StarlarkRuleClassFunctions.java
index 2e95ec5..84f9113 100644
--- a/src/main/java/com/google/devtools/build/lib/analysis/starlark/StarlarkRuleClassFunctions.java
+++ b/src/main/java/com/google/devtools/build/lib/analysis/starlark/StarlarkRuleClassFunctions.java
@@ -34,7 +34,6 @@
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;
import com.google.common.collect.ImmutableSet;
-import com.google.devtools.build.lib.actions.Artifact;
import com.google.devtools.build.lib.analysis.Allowlist;
import com.google.devtools.build.lib.analysis.BaseRuleClasses;
import com.google.devtools.build.lib.analysis.RuleDefinitionEnvironment;
@@ -117,7 +116,7 @@
import net.starlark.java.syntax.Location;
/** A helper class to provide an easier API for Starlark rule definitions. */
-public class StarlarkRuleClassFunctions implements StarlarkRuleFunctionsApi<Artifact> {
+public class StarlarkRuleClassFunctions implements StarlarkRuleFunctionsApi {
// A cache for base rule classes (especially tests).
private static final LoadingCache<String, Label> labelCache =
Caffeine.newBuilder().build(Label::parseCanonical);
diff --git a/src/main/java/com/google/devtools/build/lib/bazel/bzlmod/ModuleExtensionContext.java b/src/main/java/com/google/devtools/build/lib/bazel/bzlmod/ModuleExtensionContext.java
index 0cf2fd5..90d1f9b 100644
--- a/src/main/java/com/google/devtools/build/lib/bazel/bzlmod/ModuleExtensionContext.java
+++ b/src/main/java/com/google/devtools/build/lib/bazel/bzlmod/ModuleExtensionContext.java
@@ -95,9 +95,10 @@
structField = true,
doc =
"A list of all the Bazel modules in the external dependency graph, each of which is a <a"
- + " href=\"bazel_module.html\">bazel_module</a> object that exposes all the tags it"
- + " specified for this module extension. The iteration order of this dictionary is"
- + " guaranteed to be the same as breadth-first search starting from the root module.")
+ + " href=\"../builtins/bazel_module.html\">bazel_module</a> object that exposes all"
+ + " the tags it specified for this module extension. The iteration order of this"
+ + " dictionary is guaranteed to be the same as breadth-first search starting from the"
+ + " root module.")
public StarlarkList<StarlarkBazelModule> getModules() {
return modules;
}
@@ -106,12 +107,14 @@
name = "is_dev_dependency",
doc =
"Returns whether the given tag was specified on the result of a <a "
- + "href=\"globals.html#use_extension\">use_extension</a> call with "
+ + "href=\"../globals/module.html#use_extension\">use_extension</a> call with "
+ "<code>devDependency = True</code>.",
parameters = {
@Param(
name = "tag",
- doc = "A tag obtained from <a href=\"bazel_module.html#tags\">bazel_module.tags</a>.",
+ doc =
+ "A tag obtained from <a"
+ + " href=\"../builtins/bazel_module.html#tags\">bazel_module.tags</a>.",
allowedTypes = {@ParamType(type = TypeCheckedTag.class)})
})
public boolean isDevDependency(TypeCheckedTag tag) {
diff --git a/src/main/java/com/google/devtools/build/lib/collect/nestedset/Depset.java b/src/main/java/com/google/devtools/build/lib/collect/nestedset/Depset.java
index 8031988..ef4e611 100644
--- a/src/main/java/com/google/devtools/build/lib/collect/nestedset/Depset.java
+++ b/src/main/java/com/google/devtools/build/lib/collect/nestedset/Depset.java
@@ -63,8 +63,8 @@
+ " If you need a general set datatype, you can"
+ " simulate one using a dictionary where all keys map to <code>True</code>."
+ "<p>Depsets are immutable. They should be created using their <a"
- + " href=\"globals.html#depset\">constructor function</a> and merged or augmented with"
- + " other depsets via the <code>transitive</code> argument. "
+ + " href=\"../globals/bzl.html#depset\">constructor function</a> and merged or"
+ + " augmented with other depsets via the <code>transitive</code> argument. "
+ "<p>The <code>order</code> parameter determines the"
+ " kind of traversal that is done to convert the depset to an iterable. There are"
+ " four possible values:"
diff --git a/src/main/java/com/google/devtools/build/lib/packages/StarlarkLibrary.java b/src/main/java/com/google/devtools/build/lib/packages/StarlarkLibrary.java
index b9922d9..085d3bf 100644
--- a/src/main/java/com/google/devtools/build/lib/packages/StarlarkLibrary.java
+++ b/src/main/java/com/google/devtools/build/lib/packages/StarlarkLibrary.java
@@ -76,8 +76,8 @@
/** Proto defines the "proto" Starlark module of utilities for protocol message processing. */
@StarlarkBuiltin(
- name = "ProtoModule", // not "proto", to avoid conflict with ctx.fragments.proto data type
- category = DocCategory.BUILTIN,
+ name = "proto",
+ category = DocCategory.TOP_LEVEL_MODULE,
doc = "A module for protocol message processing.")
static final class Proto implements StarlarkValue {
@@ -266,11 +266,12 @@
@StarlarkMethod(
name = "depset",
doc =
- "Creates a <a href=\"depset.html\">depset</a>. The <code>direct</code> parameter is a"
- + " list of direct elements of the depset, and <code>transitive</code> parameter is"
- + " a list of depsets whose elements become indirect elements of the created"
- + " depset. The order in which elements are returned when the depset is converted"
- + " to a list is specified by the <code>order</code> parameter. See the <a"
+ "Creates a <a href=\"../builtins/depset.html\">depset</a>. The <code>direct</code>"
+ + " parameter is a list of direct elements of the depset, and"
+ + " <code>transitive</code> parameter is a list of depsets whose elements become"
+ + " indirect elements of the created depset. The order in which elements are"
+ + " returned when the depset is converted to a list is specified by the"
+ + " <code>order</code> parameter. See the <a"
+ " href=\"https://bazel.build/extending/depsets\">Depsets overview</a> for more"
+ " information.\n" //
+ "<p>All"
@@ -312,7 +313,7 @@
defaultValue = "\"default\"",
doc =
"The traversal strategy for the new depset. See "
- + "<a href=\"depset.html\">here</a> for the possible values.",
+ + "<a href=\"../builtins/depset.html\">here</a> for the possible values.",
named = true),
@Param(
name = "transitive",
@@ -349,7 +350,7 @@
positional = true,
doc =
"A dict that maps configuration conditions to values. Each key is a "
- + "<a href=\"Label.html\">Label</a> or a label string"
+ + "<a href=\"../builtins/Label.html\">Label</a> or a label string"
+ " that identifies a config_setting or constraint_value instance. See the"
+ " <a href=\"https://bazel.build/rules/macros#label-resolution\">"
+ "documentation on macros</a> for when to use a Label instead of a string."),
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/ActionApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/ActionApi.java
index fadb27c..af8f209 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/ActionApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/ActionApi.java
@@ -33,14 +33,14 @@
category = DocCategory.BUILTIN,
doc =
"An action created during rule analysis.<p>This object is visible for the purpose of"
- + " testing, and may be obtained from an <a href=\"globals.html#Actions\">Actions</a>"
- + " provider. It is normally not necessary to access <code>Action</code> objects or"
- + " their fields within a rule's implementation function. You may instead want to see"
- + " the <a href='https://bazel.build/extending/rules#actions'>Rules page</a> for a"
- + " general discussion of how to use actions when defining custom rules, or the <a"
- + " href='actions.html'>API reference</a> for creating actions.<p>Some fields of this"
- + " object are only applicable for certain kinds of actions. Fields that are"
- + " inapplicable are set to <code>None</code>.")
+ + " testing, and may be obtained from an <code>Actions</code> provider. It is normally"
+ + " not necessary to access <code>Action</code> objects or their fields within a rule's"
+ + " implementation function. You may instead want to see the <a"
+ + " href='https://bazel.build/extending/rules#actions'>Rules page</a> for a general"
+ + " discussion of how to use actions when defining custom rules, or the <a"
+ + " href='../builtins/actions.html'>API reference</a> for creating actions.<p>Some"
+ + " fields of this object are only applicable for certain kinds of actions. Fields that"
+ + " are inapplicable are set to <code>None</code>.")
public interface ActionApi extends StarlarkValue {
@StarlarkMethod(name = "mnemonic", structField = true, doc = "The mnemonic for this action.")
@@ -61,11 +61,11 @@
@StarlarkMethod(
name = "argv",
doc =
- "For actions created by <a href=\"actions.html#run\">ctx.actions.run()</a> "
- + "or <a href=\"actions.html#run_shell\">ctx.actions.run_shell()</a> an immutable "
- + "list of the arguments for the command line to be executed. Note that "
- + "for shell actions the first two arguments will be the shell path "
- + "and <code>\"-c\"</code>.",
+ "For actions created by <a href=\"../builtins/actions.html#run\">ctx.actions.run()</a> or"
+ + " <a href=\"../builtins/actions.html#run_shell\">ctx.actions.run_shell()</a> an"
+ + " immutable list of the arguments for the command line to be executed. Note that"
+ + " for shell actions the first two arguments will be the shell path and"
+ + " <code>\"-c\"</code>.",
structField = true,
allowReturnNones = true)
@Nullable
@@ -74,14 +74,14 @@
@StarlarkMethod(
name = "args",
doc =
- "A list of frozen <a href=\"Args.html\">Args</a> objects containing information about"
- + " the action arguments. These objects contain accurate argument information,"
- + " including arguments involving expanded action output directories. However, <a"
- + " href=\"Args.html\">Args</a> objects are not readable in the analysis phase. For"
- + " a less accurate account of arguments which is available in the analysis phase,"
- + " see <a href=\"#argv\">argv</a>."
- + " <p>Note that some types of actions do not yet support exposure of this field."
- + " For such action types, this is <code>None</code>.",
+ "A list of frozen <a href=\"../builtins/Args.html\">Args</a> objects containing"
+ + " information about the action arguments. These objects contain accurate argument"
+ + " information, including arguments involving expanded action output directories."
+ + " However, <a href=\"../builtins/Args.html\">Args</a> objects are not readable in"
+ + " the analysis phase. For a less accurate account of arguments which is available"
+ + " in the analysis phase, see <a href=\"#argv\">argv</a>. <p>Note that some types of"
+ + " actions do not yet support exposure of this field. For such action types, this is"
+ + " <code>None</code>.",
structField = true,
allowReturnNones = true)
@Nullable
@@ -101,12 +101,13 @@
@StarlarkMethod(
name = "content",
doc =
- "For actions created by <a href=\"actions.html#write\">ctx.actions.write()</a> or "
- + "<a href=\"actions.html#expand_template\">ctx.actions.expand_template()</a>,"
+ "For actions created by <a"
+ + " href=\"../builtins/actions.html#write\">ctx.actions.write()</a> or <a"
+ + " href=\"../builtins/actions.html#expand_template\">ctx.actions.expand_template()</a>,"
+ " the contents of the file to be written, if those contents can be computed during "
- + " the analysis phase. The value is <code>None</code> if the contents cannot be "
- + "determined until the execution phase, such as when a directory in an "
- + "<a href=\"Args.html\">Args</a> object needs to be expanded.",
+ + " the analysis phase. The value is <code>None</code> if the contents cannot be"
+ + " determined until the execution phase, such as when a directory in an <a"
+ + " href=\"../builtins/Args.html\">Args</a> object needs to be expanded.",
structField = true,
allowReturnNones = true)
@Nullable
@@ -115,8 +116,8 @@
@StarlarkMethod(
name = "substitutions",
doc =
- "For actions created by "
- + "<a href=\"actions.html#expand_template\">ctx.actions.expand_template()</a>,"
+ "For actions created by <a"
+ + " href=\"../builtins/actions.html#expand_template\">ctx.actions.expand_template()</a>,"
+ " an immutable dict holding the substitution mapping.",
structField = true,
allowReturnNones = true)
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/BuildConfigurationApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/BuildConfigurationApi.java
index b6b762c..2a2f2d0 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/BuildConfigurationApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/BuildConfigurationApi.java
@@ -71,7 +71,7 @@
"A boolean that tells whether code coverage is enabled for this run. Note that this does"
+ " not compute whether a specific rule should be instrumented for code coverage data"
+ " collection. For that, see the <a"
- + " href=\"ctx.html#coverage_instrumented\"><code>ctx.coverage_instrumented</code></a>"
+ + " href=\"../builtins/ctx.html#coverage_instrumented\"><code>ctx.coverage_instrumented</code></a>"
+ " function.")
boolean isCodeCoverageEnabled();
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/CommandLineArgsApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/CommandLineArgsApi.java
index 75c7126..e5272bd 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/CommandLineArgsApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/CommandLineArgsApi.java
@@ -34,15 +34,15 @@
doc =
"An object that encapsulates, in a memory-efficient way, the data needed to build part or "
+ "all of a command line."
- + ""
- + "<p>It often happens that an action requires a large command line containing values "
- + "accumulated from transitive dependencies. For example, a linker command line might "
- + "list every object file needed by all of the libraries being linked. It is best "
- + "practice to store such transitive data in <a href='depset.html'><code>depset"
- + "</code></a>s, so that they can be shared by multiple targets. However, if the rule "
- + "author had to convert these depsets into lists of strings in order to construct an "
- + "action command line, it would defeat this memory-sharing optimization."
- + ""
+ + "" //
+ + "<p>It often happens that an action requires a large command line containing values"
+ + " accumulated from transitive dependencies. For example, a linker command line might"
+ + " list every object file needed by all of the libraries being linked. It is best"
+ + " practice to store such transitive data in <a"
+ + " href='../builtins/depset.html'><code>depset</code></a>s, so that they can be shared"
+ + " by multiple targets. However, if the rule author had to convert these depsets into"
+ + " lists of strings in order to construct an action command line, it would defeat this"
+ + " memory-sharing optimization." //
+ "<p>For this reason, the action-constructing functions accept <code>Args</code> "
+ "objects in addition to strings. Each <code>Args</code> object represents a "
+ "concatenation of strings and depsets, with optional transformations for "
@@ -51,27 +51,27 @@
+ "line. This helps defer any expensive copying until after the analysis phase is "
+ "complete. See the <a href='https://bazel.build/rules/performance'>Optimizing "
+ "Performance</a> page for more information."
- + ""
- + "<p><code>Args</code> are constructed by calling <a href='actions.html#args'><code>"
- + "ctx.actions.args()</code></a>. They can be passed as the <code>arguments</code> "
- + "parameter of <a href='actions.html#run'><code>ctx.actions.run()</code></a> or "
- + "<a href='actions.html#run_shell'><code>ctx.actions.run_shell()</code></a>. Each "
- + "mutation of an <code>Args</code> object appends values to the eventual command "
- + "line."
- + ""
+ + "" //
+ + "<p><code>Args</code> are constructed by calling <a"
+ + " href='../builtins/actions.html#args'><code>ctx.actions.args()</code></a>. They can"
+ + " be passed as the <code>arguments</code> parameter of <a"
+ + " href='../builtins/actions.html#run'><code>ctx.actions.run()</code></a> or <a"
+ + " href='../builtins/actions.html#run_shell'><code>ctx.actions.run_shell()</code></a>."
+ + " Each mutation of an <code>Args</code> object appends values to the eventual command"
+ + " line." //
+ "<p>The <code>map_each</code> feature allows you to customize how items are "
+ "transformed into strings. If you do not provide a <code>map_each</code> function, "
+ "the standard conversion is as follows: "
- + "<ul>"
- + "<li>Values that are already strings are left as-is."
- + "<li><a href='File.html'><code>File</code></a> objects are turned into their "
- + " <code>File.path</code> values."
+ + "<ul>" //
+ + "<li>Values that are already strings are left as-is." //
+ + "<li><a href='../builtins/File.html'><code>File</code></a> objects are turned into"
+ + " their <code>File.path</code> values." //
+ "<li>All other types are turned into strings in an <i>unspecified</i> manner. For "
+ " this reason, you should avoid passing values that are not of string or "
+ " <code>File</code> type to <code>add()</code>, and if you pass them to "
+ " <code>add_all()</code> or <code>add_joined()</code> then you should provide a "
+ " <code>map_each</code> function."
- + "</ul>"
+ + "</ul>" //
+ ""
+ "<p>When using string formatting (<code>format</code>, <code>format_each</code>, and "
+ "<code>format_joined</code> params of the <code>add*()</code> methods), the format "
@@ -79,7 +79,7 @@
+ "except that the template must have exactly one substitution placeholder and it must "
+ "be <code>%s</code>. Literal percents may be escaped as <code>%%</code>. Formatting "
+ "is applied after the value is converted to a string as per the above."
- + ""
+ + "" //
+ "<p>Each of the <code>add*()</code> methods have an alternate form that accepts an "
+ "extra positional parameter, an \"arg name\" string to insert before the rest of the "
+ "arguments. For <code>add_all</code> and <code>add_joined</code> the extra string "
@@ -87,12 +87,12 @@
+ "For instance, the same usage can add either <code>--foo val1 val2 val3 --bar"
+ "</code> or just <code>--bar</code> to the command line, depending on whether the "
+ "given sequence contains <code>val1..val3</code> or is empty."
- + ""
+ + "" //
+ "<p>If the size of the command line can grow longer than the maximum size allowed by "
+ "the system, the arguments can be spilled over into parameter files. See "
+ "<a href='#use_param_file'><code>use_param_file()</code></a> and "
+ "<a href='#set_param_file_format'><code>set_param_file_format()</code></a>."
- + ""
+ + "" //
+ "<p>Example: Suppose we wanted to generate the command line: "
+ "<pre>\n"
+ "--foo foo1.txt foo2.txt ... fooN.txt --bar bar1.txt,bar2.txt,...,barM.txt --baz\n"
@@ -211,45 +211,35 @@
positional = false,
defaultValue = "None",
doc =
- "A function that converts each item to zero or more strings, which may be further "
- + "processed before appending. If this param is not provided, the standard "
- + "conversion is used."
- + ""
- + "<p>The function is passed either one or two positional arguments: the item "
- + "to convert, followed by an optional "
- + "<a href='DirectoryExpander.html'><code>DirectoryExpander"
- + "</code></a>. The second argument will be passed only if the supplied "
- + "function is user-defined (not built-in) and declares more than one "
- + "parameter."
- + "<p>The return value's type depends on how many arguments are to be produced "
- + "for the item:"
- + "<ul>"
- + "<li>In the common case when each item turns into one string, the function "
- + " should return that string."
- + "<li>If the item is to be filtered out entirely, the function should return "
- + " <code>None</code>."
- + "<li>If the item turns into multiple strings, the function returns a list of "
- + " those strings."
- + "</ul>"
- + "Returning a single string or <code>None</code> has the same effect as "
- + "returning a list of length 1 or length 0 respectively. However, it is more "
- + "efficient and readable to avoid creating a list where it is not needed."
- + ""
- + "<p>Ordinarily, items that are directories are automatically expanded to "
- + "their contents when <code>expand_directories=True</code> is set. However, "
- + "this will not expand directories contained inside other values -- for "
- + "instance, when the items are structs that have directories as fields. In "
- + "this situation, the <code>DirectoryExpander</code> argument can be applied "
- + "to manually obtain the files of a given directory."
- + ""
- + "<p>To avoid unintended retention of large analysis-phase data structures "
- + "into the execution phase, the <code>map_each</code> function must be "
- + "declared by a top-level <code>def</code> statement; it may not be a "
- + "nested function closure by default."
- + ""
- + "<p><i>Warning:</i> <a href='globals.html#print'><code>print()</code></a> "
- + "statements that are executed during the call to <code>map_each</code> will "
- + "not produce any visible output."),
+ "A function that converts each item to zero or more strings, which may be further"
+ + " processed before appending. If this param is not provided, the standard"
+ + " conversion is used.<p>The function is passed either one or two positional"
+ + " arguments: the item to convert, followed by an optional <a"
+ + " href='../builtins/DirectoryExpander.html'><code>DirectoryExpander</code>"
+ + "</a>. The second argument will be passed only if the supplied function is"
+ + " user-defined (not built-in) and declares more than one parameter.<p>The"
+ + " return value's type depends on how many arguments are to be produced for"
+ + " the item:<ul><li>In the common case when each item turns into one string,"
+ + " the function should return that string.<li>If the item is to be"
+ + " filtered out entirely, the function should return "
+ + " <code>None</code>.<li>If the item turns into multiple strings, the function"
+ + " returns a list of those strings.</ul>Returning a single string or"
+ + " <code>None</code> has the same effect as returning a list of length 1 or"
+ + " length 0 respectively. However, it is more efficient and readable to avoid"
+ + " creating a list where it is not needed.<p>Ordinarily, items that are"
+ + " directories are automatically expanded to their contents when"
+ + " <code>expand_directories=True</code> is set. However, this will not expand"
+ + " directories contained inside other values -- for instance, when the items"
+ + " are structs that have directories as fields. In this situation, the"
+ + " <code>DirectoryExpander</code> argument can be applied to manually obtain"
+ + " the files of a given directory.<p>To avoid unintended retention of large"
+ + " analysis-phase data structures into the execution phase, the"
+ + " <code>map_each</code> function must be declared by a top-level"
+ + " <code>def</code> statement; it may not be a nested function closure by"
+ + " default.<p><i>Warning:</i> <a"
+ + " href='../globals/all.html#print'><code>print()</code></a> statements that"
+ + " are executed during the call to <code>map_each</code> will not produce any"
+ + " visible output."),
@Param(
name = "format_each",
allowedTypes = {
@@ -389,7 +379,7 @@
doc =
"A delimiter string used to join together the strings obtained from applying "
+ "<code>map_each</code> and <code>format_each</code>, in the same manner as "
- + "<a href='string.html#join'><code>string.join()</code></a>."),
+ + "<a href='../core/string.html#join'><code>string.join()</code></a>."),
@Param(
name = "map_each",
allowedTypes = {
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/DefaultInfoApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/DefaultInfoApi.java
index 6a26bdf..bd90d5d 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/DefaultInfoApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/DefaultInfoApi.java
@@ -50,10 +50,10 @@
@StarlarkMethod(
name = "files",
doc =
- "A <a href='depset.html'><code>depset</code></a> of "
- + "<a href='File.html'><code>File</code></a> objects representing the default "
- + "outputs to build when this target is specified on the bazel command line. By "
- + "default it is all predeclared outputs.",
+ "A <a href='../builtins/depset.html'><code>depset</code></a> of <a"
+ + " href='../builtins/File.html'><code>File</code></a> objects representing the"
+ + " default outputs to build when this target is specified on the bazel command line."
+ + " By default it is all predeclared outputs.",
structField = true,
allowReturnNones = true)
@Nullable
@@ -62,8 +62,8 @@
@StarlarkMethod(
name = "files_to_run",
doc =
- "A <a href='FilesToRunProvider.html'><code>FilesToRunProvider</code></a> object "
- + "containing information about the executable and runfiles of the target.",
+ "A <a href='../providers/FilesToRunProvider.html'><code>FilesToRunProvider</code></a>"
+ + " object containing information about the executable and runfiles of the target.",
structField = true,
allowReturnNones = true)
@Nullable
@@ -111,10 +111,10 @@
positional = false,
defaultValue = "None",
doc =
- "A <a href='depset.html'><code>depset</code></a> of <a"
- + " href='File.html'><code>File</code></a> objects representing the default"
- + " outputs to build when this target is specified on the bazel command"
- + " line. By default it is all predeclared outputs."),
+ "A <a href='../builtins/depset.html'><code>depset</code></a> of <a"
+ + " href='../builtins/File.html'><code>File</code></a> objects representing"
+ + " the default outputs to build when this target is specified on the bazel"
+ + " command line. By default it is all predeclared outputs."),
@Param(
name = "runfiles",
allowedTypes = {
@@ -165,11 +165,11 @@
defaultValue = "None",
doc =
"If this rule is marked <a"
- + " href='globals.html#rule.executable'><code>executable</code></a> or <a"
- + " href='globals.html#rule.test'><code>test</code></a>, this is a <a"
- + " href='File.html'><code>File</code></a> object representing the file that"
- + " should be executed to run the target. By default it is the predeclared"
- + " output <code>ctx.outputs.executable</code>.")
+ + " href='../globals/bzl.html#rule.executable'><code>executable</code></a> or"
+ + " <a href='../globals/bzl.html#rule.test'><code>test</code></a>, this is a"
+ + " <a href='../builtins/File.html'><code>File</code></a> object representing"
+ + " the file that should be executed to run the target. By default it is the"
+ + " predeclared output <code>ctx.outputs.executable</code>.")
},
selfCall = true,
useStarlarkThread = true)
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/DirectoryExpander.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/DirectoryExpander.java
index 3cd8d9c..63f42ab 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/DirectoryExpander.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/DirectoryExpander.java
@@ -26,10 +26,10 @@
name = "DirectoryExpander",
category = DocCategory.BUILTIN,
doc =
- "Expands directories created by <a href='actions.html#declare_directory'>"
+ "Expands directories created by <a href='../builtins/actions.html#declare_directory'>"
+ "<code>ctx.actions.declare_directory</code></a>"
+ " during the execution phase. This is useful to expand directories in "
- + "<a href='Args.html#add_all.map_each'><code>map_each</code></a>.")
+ + "<a href='../builtins/Args.html#add_all.map_each'><code>map_each</code></a>.")
public interface DirectoryExpander extends StarlarkValue {
@StarlarkMethod(
name = "expand",
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/FileApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/FileApi.java
index ef1b59d..a3b444c 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/FileApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/FileApi.java
@@ -37,7 +37,7 @@
+ "information."
+ "" // curse google-java-format b/145078219
+ "<p>When a <code>File</code> is passed to an <a"
- + " href='Args.html'><code>Args</code></a> object without using a"
+ + " href='../builtins/Args.html'><code>Args</code></a> object without using a"
+ " <code>map_each</code> function, it is converted to a string by taking the value of"
+ " its <code>path</code> field.")
public interface FileApi extends StarlarkValue {
@@ -103,25 +103,26 @@
name = "path",
structField = true,
doc =
- "The execution path of this file, relative to the workspace's execution directory. It "
- + "consists of two parts, an optional first part called the <i>root</i> (see also "
- + "the <a href=\"root.html\">root</a> module), and the second part which is the "
- + "<code>short_path</code>. The root may be empty, which it usually is for "
- + "non-generated files. For generated files it usually contains a "
- + "configuration-specific path fragment that encodes things like the target CPU "
- + "architecture that was used while building said file. Use the "
- + "<code>short_path</code> for the path under which the file is mapped if it's in "
- + "the runfiles of a binary.")
+ "The execution path of this file, relative to the workspace's execution directory. It"
+ + " consists of two parts, an optional first part called the <i>root</i> (see also"
+ + " the <a href=\"../builtins/root.html\">root</a> module), and the second part which"
+ + " is the <code>short_path</code>. The root may be empty, which it usually is for"
+ + " non-generated files. For generated files it usually contains a"
+ + " configuration-specific path fragment that encodes things like the target CPU"
+ + " architecture that was used while building said file. Use the"
+ + " <code>short_path</code> for the path under which the file is mapped if it's in"
+ + " the runfiles of a binary.")
String getExecPathString();
@StarlarkMethod(
name = "tree_relative_path",
structField = true,
doc =
- "The path of this file relative to the root of the ancestor's tree, if the ancestor's "
- + "<a href=\"#is_directory\">is_directory</a> field is true. <code>tree_relative_path"
- + "</code> is only available for expanded files of a directory in an action command, "
- + "i.e. <a href=\"Args.html#add_all\">Args.add_all()</a>. For other types of files, "
- + "it is an error to access this field.")
+ "The path of this file relative to the root of the ancestor's tree, if the ancestor's <a"
+ + " href=\"#is_directory\">is_directory</a> field is true."
+ + " <code>tree_relative_path</code> is only available for expanded files of a"
+ + " directory in an action command, i.e. <a"
+ + " href=\"../builtins/Args.html#add_all\">Args.add_all()</a>. For other types of"
+ + " files, it is an error to access this field.")
String getTreeRelativePathString() throws EvalException;
}
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/FragmentCollectionApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/FragmentCollectionApi.java
index d7b9a85..1cc123c 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/FragmentCollectionApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/FragmentCollectionApi.java
@@ -28,7 +28,7 @@
+ " context. Access a specific fragment by its field name. For example,"
+ " <code>ctx.fragments.java</code> <p>Only configuration fragments which are declared"
+ " in the rule definition may be accessed in this collection.</p><p>See the <a"
- + " href=\"https://bazel.build/rules/lib/starlark-configuration-fragment\">configuration"
+ + " href=\"../fragments\">configuration"
+ " fragment reference</a> for a list of available fragments and the <a"
+ " href=\"https://bazel.build/extending/rules#configuration_fragments\">rules"
+ " documentation</a> for how to use them.")
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/LateBoundDefaultApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/LateBoundDefaultApi.java
index 9664323..52a0b90 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/LateBoundDefaultApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/LateBoundDefaultApi.java
@@ -28,6 +28,6 @@
+ " function, and depends on the current build configuration. For example, a"
+ " LateBoundDefault might represent the Label of the java toolchain in the current"
+ " build configuration. <p>See <a"
- + " href=\"globals.html#configuration_field\">configuration_field</a> for example"
- + " usage.")
+ + " href=\"../globals/bzl.html#configuration_field\">configuration_field</a> for"
+ + " example usage.")
public interface LateBoundDefaultApi extends StarlarkValue {}
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/RunfilesApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/RunfilesApi.java
index ab4da2b..72fa2fa 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/RunfilesApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/RunfilesApi.java
@@ -31,11 +31,11 @@
category = DocCategory.BUILTIN,
doc =
"A container of information regarding a set of files required at runtime execution. This"
- + " object should be passed via <a href=\"DefaultInfo.html\">DefaultInfo</a> in order"
- + " to tell the build system about the runfiles needed by the outputs produced by the"
- + " rule. <p>See <a"
- + " href=\"https://bazel.build/extending/rules#runfiles\">runfiles"
- + " guide</a> for details.")
+ + " object should be passed via <a"
+ + " href=\"../providers/DefaultInfo.html\">DefaultInfo</a> in order to tell the build"
+ + " system about the runfiles needed by the outputs produced by the rule. <p>See <a"
+ + " href=\"https://bazel.build/extending/rules#runfiles\">runfiles guide</a> for"
+ + " details.")
public interface RunfilesApi extends StarlarkValue {
@StarlarkMethod(name = "files", doc = "Returns the set of runfiles as files.", structField = true)
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkActionFactoryApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkActionFactoryApi.java
index c09773d..fdd8b46 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkActionFactoryApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkActionFactoryApi.java
@@ -35,8 +35,8 @@
name = "actions",
category = DocCategory.BUILTIN,
doc =
- "Module providing functions to create actions. "
- + "Access this module using <a href=\"ctx#actions\"><code>ctx.actions</code></a>.")
+ "Module providing functions to create actions. Access this module using <a"
+ + " href=\"../builtins/ctx.html#actions\"><code>ctx.actions</code></a>.")
public interface StarlarkActionFactoryApi extends StarlarkValue {
@StarlarkMethod(
@@ -52,7 +52,7 @@
+ " href='https://bazel.build/extending/rules#files'>predeclared output files</a> do"
+ " not need to be (and cannot be) declared using this function. You can obtain their"
+ " <code>File</code> objects from <a"
- + " href=\"ctx.html#outputs\"><code>ctx.outputs</code></a> instead. <a"
+ + " href=\"../builtins/ctx.html#outputs\"><code>ctx.outputs</code></a> instead. <a"
+ " href=\"https://github.com/bazelbuild/examples/tree/main/rules/computed_dependencies/hash.bzl\">See"
+ " example of use</a>.",
parameters = {
@@ -84,7 +84,7 @@
+ "current package. You must create an action that generates the directory. "
+ "The contents of the directory are not directly accessible from Starlark, "
+ "but can be expanded in an action command with "
- + "<a href=\"Args.html#add_all\"><code>Args.add_all()</code></a>. "
+ + "<a href=\"../builtins/Args.html#add_all\"><code>Args.add_all()</code></a>. "
+ "Only regular files and directories can be in the expanded contents of a "
+ "declare_directory.",
parameters = {
@@ -257,9 +257,9 @@
@ParamType(type = CommandLineArgsApi.class)
},
doc =
- "the contents of the file. "
- + "May be a either a string or an "
- + "<a href=\"actions.html#args\"><code>actions.args()</code></a> object.",
+ "the contents of the file. May be a either a string or an <a"
+ + " href=\"#args\"><code>actions.args()</code></a>"
+ + " object.",
named = true),
@Param(
name = "is_executable",
@@ -349,7 +349,7 @@
doc =
"Command line arguments of the action. "
+ "Must be a list of strings or "
- + "<a href=\"actions.html#args\"><code>actions.args()</code></a> objects."),
+ + "<a href=\"#args\"><code>actions.args()</code></a> objects."),
@Param(
name = "mnemonic",
allowedTypes = {
@@ -551,7 +551,7 @@
positional = false,
doc =
"Command line arguments of the action. Must be a list of strings or "
- + "<a href=\"actions.html#args\"><code>actions.args()</code></a> objects."
+ + "<a href=\"#args\"><code>actions.args()</code></a> objects."
+ ""
+ "<p>Bazel passes the elements in this attribute as arguments to the command."
+ "The command can access these arguments using shell variable substitutions "
@@ -590,7 +590,7 @@
+ "elements in <code>arguments</code> are made available to the command as "
+ "<code>$1</code>, <code>$2</code> (or <code>%1</code>, <code>%2</code> if "
+ "using Windows batch), etc. If <code>arguments</code> contains "
- + "any <a href=\"actions.html#args\"><code>actions.args()</code></a> objects, "
+ + "any <a href=\"#args\"><code>actions.args()</code></a> objects, "
+ "their contents are appended one by one to the command line, so "
+ "<code>$</code><i>i</i> can refer to individual strings within an Args "
+ "object. Note that if an Args object of unknown size is passed as part of "
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkAspectApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkAspectApi.java
index 6c1744d..7d7853f 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkAspectApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkAspectApi.java
@@ -23,7 +23,7 @@
name = "Aspect",
category = DocCategory.BUILTIN,
doc =
- "For more information about Aspects, please consult the <a href=\"globals.html#aspect\">"
- + "documentation of the aspect function</a> or the "
- + "<a href=\"https://bazel.build/rules/aspects\">introduction to Aspects</a>.")
+ "For more information about Aspects, please consult the <a"
+ + " href=\"../globals/bzl.html#aspect\">documentation of the aspect function</a> or the"
+ + " <a href=\"https://bazel.build/rules/aspects\">introduction to Aspects</a>.")
public interface StarlarkAspectApi extends StarlarkValue {}
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkAttrModuleApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkAttrModuleApi.java
index 8652116..cc1721d 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkAttrModuleApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkAttrModuleApi.java
@@ -43,34 +43,35 @@
"This is a top-level module for defining the attribute schemas of a rule or aspect. Each"
+ " function returns an object representing the schema of a single attribute. These"
+ " objects are used as the values of the <code>attrs</code> dictionary argument of <a"
- + " href=\"globals.html#rule\"><code>rule()</code></a> and <a"
- + " href=\"globals.html#aspect\"><code>aspect()</code></a>.<p>See the Rules page for"
- + " more on <a href='https://bazel.build/extending/rules#attributes'>defining</a> and"
- + " <a href='https://bazel.build/extending/rules#implementation_function'>using</a>"
+ + " href=\"../globals/bzl.html#rule\"><code>rule()</code></a> and <a"
+ + " href=\"../globals/bzl.html#aspect\"><code>aspect()</code></a>.<p>See the Rules page"
+ + " for more on <a href='https://bazel.build/extending/rules#attributes'>defining</a>"
+ + " and <a href='https://bazel.build/extending/rules#implementation_function'>using</a>"
+ " attributes.")
public interface StarlarkAttrModuleApi extends StarlarkValue {
// dependency and output attributes
String LABEL_PARAGRAPH =
- "<p>This attribute contains unique <a href='Label.html'><code>Label</code></a> values. If a "
- + "string is supplied in place of a <code>Label</code>, it will be converted using the "
- + "<a href='Label.html#Label'>label constructor</a>. The relative parts of the label "
- + "path, including the (possibly renamed) repository, are resolved with respect to the "
- + "instantiated target's package.";
+ "<p>This attribute contains unique <a href='../builtins/Label.html'><code>Label</code></a>"
+ + " values. If a string is supplied in place of a <code>Label</code>, it will be"
+ + " converted using the <a href='../builtins/Label.html#Label'>label constructor</a>. The"
+ + " relative parts of the label path, including the (possibly renamed) repository, are"
+ + " resolved with respect to the instantiated target's package.";
// attr.label, attr.label_list, attr.label_keyed_string_dict
String DEPENDENCY_ATTR_TEXT =
LABEL_PARAGRAPH
- + "<p>At analysis time (within the rule's implementation function), when retrieving the "
- + "attribute value from <code>ctx.attr</code>, labels are replaced by the corresponding "
- + "<a href='Target.html'><code>Target</code></a>s. This allows you to access the "
- + "providers of the current target's dependencies.";
+ + "<p>At analysis time (within the rule's implementation function), when retrieving the"
+ + " attribute value from <code>ctx.attr</code>, labels are replaced by the corresponding"
+ + " <a href='../builtins/Target.html'><code>Target</code></a>s. This allows you to access"
+ + " the providers of the current target's dependencies.";
// attr.output, attr.output_list
String OUTPUT_ATTR_TEXT =
LABEL_PARAGRAPH
- + "<p>At analysis time, the corresponding <a href='File.html'><code>File</code></a> can "
- + "be retrieved using <a href='ctx.html#outputs'><code>ctx.outputs</code></a>.";
+ + "<p>At analysis time, the corresponding <a"
+ + " href='../builtins/File.html'><code>File</code></a> can be retrieved using <a"
+ + " href='../builtins/ctx.html#outputs'><code>ctx.outputs</code></a>.";
String ALLOW_FILES_ARG = "allow_files";
String ALLOW_FILES_DOC =
@@ -127,17 +128,15 @@
String PROVIDERS_ARG = "providers";
String PROVIDERS_DOC =
- "The providers that must be given by any dependency appearing in this attribute."
- + ""
- + "<p>The format of this argument is a list of lists of providers -- <code>*Info</code> "
- + "objects returned by <a href='globals.html#provider'><code>provider()</code></a> (or "
- + "in the case of a legacy provider, its string name). The dependency must return ALL "
- + "providers mentioned in at least ONE of the inner lists. As a convenience, this "
- + "argument may also be a single-level list of providers, in which case it is wrapped in "
- + "an outer list with one element."
- + ""
- + "It is NOT required that the rule of the dependency advertises those providers "
- + "in its <code>provides<code> parameter, however, it is considered best practice.";
+ "The providers that must be given by any dependency appearing in this attribute.<p>The format"
+ + " of this argument is a list of lists of providers -- <code>*Info</code> objects"
+ + " returned by <a href='../globals/bzl.html#provider'><code>provider()</code></a> (or in"
+ + " the case of a legacy provider, its string name). The dependency must return ALL"
+ + " providers mentioned in at least ONE of the inner lists. As a convenience, this"
+ + " argument may also be a single-level list of providers, in which case it is wrapped in"
+ + " an outer list with one element.It is NOT required that the rule of the dependency"
+ + " advertises those providers in its <code>provides<code> parameter, however, it is"
+ + " considered best practice.";
String ALLOW_SINGLE_FILE_ARG = "allow_single_file";
@@ -149,10 +148,9 @@
@StarlarkMethod(
name = "int",
doc =
- "Creates a schema for an integer attribute. The value must be in the signed 32-bit"
- + " range. The corresponding "
- + "<a href='ctx.html#attr'><code>ctx.attr</code></a> attribute will be of "
- + "type <a href='int.html'><code>int</code></a>.",
+ "Creates a schema for an integer attribute. The value must be in the signed 32-bit range."
+ + " The corresponding <a href='../builtins/ctx.html#attr'><code>ctx.attr</code></a>"
+ + " attribute will be of type <a href='../core/int.html'><code>int</code></a>.",
parameters = {
@Param(
name = DEFAULT_ARG,
@@ -192,7 +190,7 @@
@StarlarkMethod(
name = "string",
- doc = "Creates a schema for a <a href='string.html#attr'>string</a> attribute.",
+ doc = "Creates a schema for a <a href='../core/string.html#attr'>string</a> attribute.",
parameters = {
@Param(
name = DEFAULT_ARG,
@@ -268,9 +266,10 @@
positional = false,
doc =
DEFAULT_DOC
- + "Use a string or the <a href=\"globals.html#Label\"><code>Label</code></a> "
- + "function to specify a default value, for example, "
- + "<code>attr.label(default = \"//a:b\")</code>."),
+ + "Use a string or the <a"
+ + " href=\"../builtins/Label.html#Label\"><code>Label</code></a> function to"
+ + " specify a default value, for example, <code>attr.label(default ="
+ + " \"//a:b\")</code>."),
@Param(
name = DOC_ARG,
allowedTypes = {@ParamType(type = String.class), @ParamType(type = NoneType.class)},
@@ -302,7 +301,7 @@
positional = false,
doc =
"This is similar to <code>allow_files</code>, with the restriction that the label "
- + "must correspond to a single <a href=\"File.html\">File</a>. "
+ + "must correspond to a single <a href=\"../builtins/File.html\">File</a>. "
+ "Access it through <code>ctx.file.<attribute_name></code>."),
@Param(
name = MANDATORY_ARG,
@@ -435,9 +434,9 @@
name = "label_list",
doc =
"<p>Creates a schema for a list-of-labels attribute. This is a dependency attribute. "
- + "The corresponding <a href='ctx.html#attr'><code>ctx.attr</code></a> "
- + "attribute will be of type <a href='list.html'>list</a> of "
- + "<a href='Target.html'><code>Target</code>s</a>.</p>"
+ + "The corresponding <a href='../builtins/ctx.html#attr'><code>ctx.attr</code></a> "
+ + "attribute will be of type <a href='../core/list.html'>list</a> of "
+ + "<a href='../builtins/Target.html'><code>Target</code>s</a>.</p>"
+ DEPENDENCY_ATTR_TEXT,
parameters = {
@Param(name = ALLOW_EMPTY_ARG, defaultValue = "True", doc = ALLOW_EMPTY_DOC, named = true),
@@ -452,9 +451,10 @@
positional = false,
doc =
DEFAULT_DOC
- + "Use strings or the <a href=\"globals.html#Label\"><code>Label</code></a> "
- + "function to specify default values, for example, "
- + "<code>attr.label_list(default = [\"//a:b\", \"//a:c\"])</code>."),
+ + "Use strings or the <a"
+ + " href=\"../builtins/Label.html#Label\"><code>Label</code></a> function to"
+ + " specify default values, for example, <code>attr.label_list(default ="
+ + " [\"//a:b\", \"//a:c\"])</code>."),
@Param(
name = DOC_ARG,
allowedTypes = {@ParamType(type = String.class), @ParamType(type = NoneType.class)},
@@ -550,10 +550,11 @@
positional = false,
doc =
DEFAULT_DOC
- + "Use strings or the <a href=\"globals.html#Label\"><code>Label</code></a> "
- + "function to specify default values, for example, "
- + "<code>attr.label_keyed_string_dict(default = "
- + "{\"//a:b\": \"value\", \"//a:c\": \"string\"})</code>."),
+ + "Use strings or the <a"
+ + " href=\"../builtins/Label.html#Label\"><code>Label</code></a> function to"
+ + " specify default values, for example,"
+ + " <code>attr.label_keyed_string_dict(default = {\"//a:b\": \"value\","
+ + " \"//a:c\": \"string\"})</code>."),
@Param(
name = DOC_ARG,
allowedTypes = {@ParamType(type = String.class), @ParamType(type = NoneType.class)},
@@ -634,8 +635,8 @@
name = "bool",
doc =
"Creates a schema for a boolean attribute. The corresponding <a"
- + " href='ctx.html#attr'><code>ctx.attr</code></a> attribute will be of type"
- + " <a href='bool.html'><code>bool</code></a>.",
+ + " href='../builtins/ctx.html#attr'><code>ctx.attr</code></a> attribute will be of"
+ + " type <a href='../core/bool.html'><code>bool</code></a>.",
parameters = {
@Param(
name = DEFAULT_ARG,
@@ -829,9 +830,9 @@
name = "Attribute",
category = DocCategory.BUILTIN,
doc =
- "Representation of a definition of an attribute. Use the <a href=\"attr.html\">attr</a> "
- + "module to create an Attribute. They are only for use with a "
- + "<a href=\"globals.html#rule\">rule</a> or an "
- + "<a href=\"globals.html#aspect\">aspect</a>.")
+ "Representation of a definition of an attribute. Use the <a"
+ + " href=\"../toplevel/attr.html\">attr</a> module to create an Attribute. They are"
+ + " only for use with a <a href=\"../globals/bzl.html#rule\">rule</a> or an <a"
+ + " href=\"../globals/bzl.html#aspect\">aspect</a>.")
interface Descriptor extends StarlarkValue {}
}
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkBuildApiGlobals.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkBuildApiGlobals.java
index c05ff28..5116a57 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkBuildApiGlobals.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkBuildApiGlobals.java
@@ -89,14 +89,14 @@
// TODO(cparsons): Provide a link to documentation for available StarlarkConfigurationFields.
doc =
"References a late-bound default value for an attribute of type <a"
- + " href=\"attr.html#label\">label</a>. A value is 'late-bound' if it requires the"
- + " configuration to be built before determining the value. Any attribute using this"
- + " as a value must"
- + " <a href=\"https://bazel.build/extending/rules#private-attributes\">be"
- + " private</a>. <p>Example usage: <p>Defining a rule attribute: <br><pre"
+ + " href=\"../toplevel/attr.html#label\">label</a>. A value is 'late-bound' if it"
+ + " requires the configuration to be built before determining the value. Any"
+ + " attribute using this as a value must <a"
+ + " href=\"https://bazel.build/extending/rules#private-attributes\">be private</a>."
+ + " <p>Example usage: <p>Defining a rule attribute: <br><pre"
+ " class=language-python>'_foo':"
- + " attr.label(default=configuration_field(fragment='java', "
- + "name='toolchain'))</pre><p>Accessing in rule implementation: <br><pre"
+ + " attr.label(default=configuration_field(fragment='java',"
+ + " name='toolchain'))</pre><p>Accessing in rule implementation: <br><pre"
+ " class=language-python> def _rule_impl(ctx):\n"
+ " foo_info = ctx.attr._foo\n"
+ " ...</pre>",
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkNativeModuleApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkNativeModuleApi.java
index 66770ad..a752784 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkNativeModuleApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkNativeModuleApi.java
@@ -15,6 +15,8 @@
package com.google.devtools.build.lib.starlarkbuildapi;
import com.google.devtools.build.docgen.annot.DocCategory;
+import com.google.devtools.build.docgen.annot.GlobalMethods;
+import com.google.devtools.build.docgen.annot.GlobalMethods.Environment;
import com.google.devtools.build.lib.cmdline.Label;
import javax.annotation.Nullable;
import net.starlark.java.annot.Param;
@@ -40,6 +42,8 @@
+ "(i.e. for macros, not for rule implementations). Attributes will ignore "
+ "<code>None</code> values, and treat them as if the attribute was unset.<br>"
+ "The following functions are also available:")
+// Methods in this class are also available at the top level in BUILD files.
+@GlobalMethods(environment = Environment.BUILD)
public interface StarlarkNativeModuleApi extends StarlarkValue {
@StarlarkMethod(
@@ -246,19 +250,20 @@
@StarlarkMethod(
name = "package_relative_label",
doc =
- "Converts the input string into a <a href='Label'>Label</a> object, in the context of the"
- + " package currently being initialized (that is, the <code>BUILD</code> file for"
- + " which the current macro is executing). If the input is already a"
- + " <code>Label</code>, it is returned unchanged.<p>This function may only be called"
- + " while evaluating a BUILD file and the macros it directly or indirectly calls; it"
- + " may not be called in (for instance) a rule implementation function. <p>The result"
- + " of this function is the same <code>Label</code> value as would be produced by"
- + " passing the given string to a label-valued attribute of a target declared in the"
- + " BUILD file. <p><i>Usage note:</i> The difference between this function and <a"
- + " href='Label#Label'>Label()</a></code> is that <code>Label()</code> uses the"
- + " context of the package of the <code>.bzl</code> file that called it, not the"
- + " package of the <code>BUILD</code> file. Use <code>Label()</code> when you need to"
- + " refer to a fixed target that is hardcoded into the macro, such as a compiler. Use"
+ "Converts the input string into a <a href='../builtins/Label.html'>Label</a> object, in"
+ + " the context of the package currently being initialized (that is, the"
+ + " <code>BUILD</code> file for which the current macro is executing). If the input"
+ + " is already a <code>Label</code>, it is returned unchanged.<p>This function may"
+ + " only be called while evaluating a BUILD file and the macros it directly or"
+ + " indirectly calls; it may not be called in (for instance) a rule implementation"
+ + " function. <p>The result of this function is the same <code>Label</code> value as"
+ + " would be produced by passing the given string to a label-valued attribute of a"
+ + " target declared in the BUILD file. <p><i>Usage note:</i> The difference between"
+ + " this function and <a href='../builtins/Label.html#Label'>Label()</a></code> is"
+ + " that <code>Label()</code> uses the context of the package of the"
+ + " <code>.bzl</code> file that called it, not the package of the <code>BUILD</code>"
+ + " file. Use <code>Label()</code> when you need to refer to a fixed target that is"
+ + " hardcoded into the macro, such as a compiler. Use"
+ " <code>package_relative_label()</code> when you need to normalize a label string"
+ " supplied by the BUILD file to a <code>Label</code> object. (There is no way to"
+ " convert a string to a <code>Label</code> in the context of a package other than"
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkRuleContextApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkRuleContextApi.java
index 5706380..9567c00 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkRuleContextApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkRuleContextApi.java
@@ -64,38 +64,39 @@
+ " to associate a label with the file that rules can refer to (allowing finer"
+ " dependency control) instead of referencing the whole rule.";
String EXECUTABLE_DOC =
- "A <code>struct</code> containing executable files defined in <a "
- + "href='attr.html#label'>label type attributes</a> marked as <a "
- + "href='attr.html#label.executable'><code>executable=True</code><a>. The struct "
- + "fields correspond to the attribute names. Each value in the struct is either a <a "
- + "href='File.html'><code>File</code></a> or <code>None</code>. If an optional "
- + "attribute is not specified in the rule then the corresponding struct value is "
- + "<code>None</code>. If a label type is not marked as <code>executable=True</code>, no "
- + "corresponding struct field is generated. <a "
- + "href=\"https://github.com/bazelbuild/examples/blob/main/rules/actions_run/"
- + "execute.bzl\">See example of use</a>.";
+ "A <code>struct</code> containing executable files defined in <a"
+ + " href='../toplevel/attr.html#label'>label type attributes</a> marked as <a"
+ + " href='../toplevel/attr.html#label.executable'><code>executable=True</code></a>. The"
+ + " struct fields correspond to the attribute names. Each value in the struct is either a"
+ + " <a href='../builtins/File.html'><code>File</code></a> or <code>None</code>. If an"
+ + " optional attribute is not specified in the rule then the corresponding struct value"
+ + " is <code>None</code>. If a label type is not marked as <code>executable=True</code>,"
+ + " no corresponding struct field is generated. <a "
+ + "href=\"https://github.com/bazelbuild/examples/blob/main/rules/actions_run/execute.bzl\">See"
+ + " example of use</a>.";
String FILES_DOC =
- "A <code>struct</code> containing files defined in <a href='attr.html#label'>label</a> or <a"
- + " href='attr.html#label_list'>label list</a> type attributes. The struct fields"
- + " correspond to the attribute names. The struct values are <code>list</code> of <a"
- + " href='File.html'><code>File</code></a>s. It is a shortcut for:<pre"
+ "A <code>struct</code> containing files defined in <a"
+ + " href='../toplevel/attr.html#label'>label</a> or <a"
+ + " href='../toplevel/attr.html#label_list'>label list</a> type attributes. The struct"
+ + " fields correspond to the attribute names. The struct values are <code>list</code> of"
+ + " <a href='../builtins/File.html'><code>File</code></a>s. It is a shortcut for:<pre"
+ " class=language-python>[f for t in ctx.attr.<ATTR> for f in t.files]</pre> In"
+ " other words, use <code>files</code> to access the <a"
- + " href=\"https://bazel.build/extending/rules#requesting_output_files\">"
- + " default outputs</a> of a dependency. <a"
+ + " href=\"https://bazel.build/extending/rules#requesting_output_files\"> default"
+ + " outputs</a> of a dependency. <a"
+ " href=\"https://github.com/bazelbuild/examples/blob/main/rules/depsets/foo.bzl\">See"
+ " example of use</a>.";
String FILE_DOC =
- "A <code>struct</code> containing files defined in <a href='attr.html#label'>label type"
- + " attributes</a> marked as <a"
- + " href='attr.html#label.allow_single_file'><code>allow_single_file</code></a>. The"
- + " struct fields correspond to the attribute names. The struct value is always a <a"
- + " href='File.html'><code>File</code></a> or <code>None</code>. If an optional attribute"
- + " is not specified in the rule then the corresponding struct value is"
- + " <code>None</code>. If a label type is not marked as <code>allow_single_file</code>,"
- + " no corresponding struct field is generated. It is a shortcut for:<pre"
- + " class=language-python>list(ctx.attr.<ATTR>.files)[0]</pre>In other words, use"
- + " <code>file</code> to access the (singular) <a"
+ "A <code>struct</code> containing files defined in <a"
+ + " href='../toplevel/attr.html#label'>label type attributes</a> marked as <a"
+ + " href='../toplevel/attr.html#label.allow_single_file'><code>allow_single_file</code></a>."
+ + " The struct fields correspond to the attribute names. The struct value is always a <a"
+ + " href='../builtins/File.html'><code>File</code></a> or <code>None</code>. If an"
+ + " optional attribute is not specified in the rule then the corresponding struct value"
+ + " is <code>None</code>. If a label type is not marked as"
+ + " <code>allow_single_file</code>, no corresponding struct field is generated. It is a"
+ + " shortcut for:<pre class=language-python>list(ctx.attr.<ATTR>.files)[0]</pre>In"
+ + " other words, use <code>file</code> to access the (singular) <a"
+ " href=\"https://bazel.build/extending/rules#requesting_output_files\">default"
+ " output</a> of a dependency. <a"
+ " href=\"https://github.com/bazelbuild/examples/blob/main/rules/expand_template/hello.bzl\">See"
@@ -105,8 +106,8 @@
+ " href='https://bazel.build/extending/rules#attributes'>attributes</a>. The values are"
+ " provided by the user (if not, a default value is used). The attributes of the struct"
+ " and the types of their values correspond to the keys and values of the <a"
- + " href='globals.html#rule.attrs'><code>attrs</code> dict</a> provided to the <a"
- + " href='globals.html#rule'><code>rule</code> function</a>. <a "
+ + " href='../globals/bzl.html#rule.attrs'><code>attrs</code> dict</a> provided to the <a"
+ + " href='../globals/bzl.html#rule'><code>rule</code> function</a>. <a "
+ "href=\"https://github.com/bazelbuild/examples/blob/main/rules/attributes/printer.bzl\">See"
+ " example of use</a>.";
String SPLIT_ATTR_DOC =
@@ -119,34 +120,36 @@
+ "merged together.";
String OUTPUTS_DOC =
"A pseudo-struct containing all the predeclared output files, represented by <a"
- + " href='File.html'><code>File</code></a> objects. See the <a"
+ + " href='../builtins/File.html'><code>File</code></a> objects. See the <a"
+ " href='https://bazel.build/extending/rules#files'>Rules page</a> for more information"
+ " and examples.<p>This field does not exist on aspect contexts, since aspects do not"
+ " have predeclared outputs.<p>The fields of this object are defined as follows. It is"
+ " an error if two outputs produce the same field name or have the same label.<ul><li>"
- + " If the rule declares an <a href='globals.html#rule.outputs'><code>outputs</code></a>"
- + " dict, then for every entry in the dict, there is a field whose name is the key and"
- + " whose value is the corresponding <code>File</code>.<li>For every attribute of type <a"
- + " href='attr.html#output'><code>attr.output</code></a> that the rule declares, there is"
- + " a field whose name is the attribute's name. If the target specified a label for that"
- + " attribute, then the field value is the corresponding <code>File</code>; otherwise the"
- + " field value is <code>None</code>.<li>For every attribute of type <a"
- + " href='attr.html#output_list'><code>attr.output_list</code></a> that the rule"
- + " declares, there is a field whose name is the attribute's name. The field value is a"
- + " list of <code>File</code> objects corresponding to the labels given for that"
+ + " If the rule declares an <a"
+ + " href='../globals/bzl.html#rule.outputs'><code>outputs</code></a> dict, then for every"
+ + " entry in the dict, there is a field whose name is the key and whose value is the"
+ + " corresponding <code>File</code>.<li>For every attribute of type <a"
+ + " href='../toplevel/attr.html#output'><code>attr.output</code></a> that the rule"
+ + " declares, there is a field whose name is the attribute's name. If the target"
+ + " specified a label for that attribute, then the field value is the corresponding"
+ + " <code>File</code>; otherwise the field value is <code>None</code>.<li>For every"
+ + " attribute of type <a"
+ + " href='../toplevel/attr.html#output_list'><code>attr.output_list</code></a> that the"
+ + " rule declares, there is a field whose name is the attribute's name. The field value"
+ + " is a list of <code>File</code> objects corresponding to the labels given for that"
+ " attribute in the target, or an empty list if the attribute was not specified in the"
+ " target.<li><b>(Deprecated)</b> If the rule is marked <a"
- + " href='globals.html#rule.executable'><code>executable</code></a> or <a"
- + " href='globals.html#rule.test'><code>test</code></a>, there is a field named"
+ + " href='../globals/bzl.html#rule.executable'><code>executable</code></a> or <a"
+ + " href='../globals/bzl.html#rule.test'><code>test</code></a>, there is a field named"
+ " <code>\"executable\"</code>, which is the default executable. It is recommended that"
+ " instead of using this, you pass another file (either predeclared or not) to the"
+ " <code>executable</code> arg of <a"
- + " href='DefaultInfo.html'><code>DefaultInfo</code></a>.</ul>";
+ + " href='../providers/DefaultInfo.html'><code>DefaultInfo</code></a>.</ul>";
@StarlarkMethod(
name = "default_provider",
structField = true,
- doc = "Deprecated. Use <a href=\"DefaultInfo.html\">DefaultInfo</a> instead.")
+ doc = "Deprecated. Use <a href=\"../providers/DefaultInfo.html\">DefaultInfo</a> instead.")
ProviderApi getDefaultProvider();
@StarlarkMethod(
@@ -158,10 +161,10 @@
@StarlarkMethod(
name = "created_actions",
doc =
- "For rules with <a href=\"globals.html#rule._skylark_testable\">_skylark_testable</a>"
- + " set to <code>True</code>, this returns an <a"
- + " href=\"globals.html#Actions\">Actions</a> provider representing all actions"
- + " created so far for the current rule. For all other rules, returns"
+ "For rules with <a"
+ + " href=\"../globals/bzl.html#rule._skylark_testable\">_skylark_testable</a> set to"
+ + " <code>True</code>, this returns an <code>Actions</code> provider representing all"
+ + " actions created so far for the current rule. For all other rules, returns"
+ " <code>None</code>. Note that the provider is not updated when subsequent actions"
+ " are created, so you will have to call this function again if you wish to inspect"
+ " them. <br/><br/>This is intended to help write tests for rule-implementation"
@@ -206,7 +209,7 @@
name = "configuration",
structField = true,
doc =
- "The default configuration. See the <a href=\"configuration.html\">"
+ "The default configuration. See the <a href=\"../builtins/configuration.html\">"
+ "configuration</a> type for more details.")
BuildConfigurationApi getConfiguration() throws EvalException;
@@ -223,17 +226,16 @@
@StarlarkMethod(
name = "coverage_instrumented",
doc =
- "Returns whether code coverage instrumentation should be generated when performing "
- + "compilation actions for this rule or, if <code>target</code> is provided, the "
- + "rule specified by that Target. (If a non-rule or a Starlark rule Target is "
- + "provided, this returns False.) Checks if the sources of the current rule "
- + "(if no Target is provided) or the sources of Target should be instrumented "
- + "based on the --instrumentation_filter and "
- + "--instrument_test_targets config settings. "
- + "This differs from <code>coverage_enabled</code> in the "
- + "<a href=\"configuration.html\">configuration</a>, which notes whether coverage "
- + "data collection is enabled for the entire run, but not whether a specific "
- + "target should be instrumented.",
+ "Returns whether code coverage instrumentation should be generated when performing"
+ + " compilation actions for this rule or, if <code>target</code> is provided, the"
+ + " rule specified by that Target. (If a non-rule or a Starlark rule Target is"
+ + " provided, this returns False.) Checks if the sources of the current rule (if no"
+ + " Target is provided) or the sources of Target should be instrumented based on the"
+ + " --instrumentation_filter and --instrument_test_targets config settings. This"
+ + " differs from <code>coverage_enabled</code> in the <a"
+ + " href=\"../builtins/configuration.html\">configuration</a>, which notes whether"
+ + " coverage data collection is enabled for the entire run, but not whether a"
+ + " specific target should be instrumented.",
parameters = {
@Param(
name = "target",
@@ -342,21 +344,16 @@
@StarlarkMethod(
name = "new_file",
doc =
- "DEPRECATED. Use <a href=\"actions.html#declare_file\">ctx.actions.declare_file</a>. <br>"
- + "Creates a file object. There are four possible signatures to this method:<br><ul>"
- + ""
- + "<li>new_file(filename): Creates a file object with the given filename in the "
- + "current package.</li>"
- + ""
- + "<li>new_file(file_root, filename): Creates a file object with the given "
- + "filename under the given file root.</li>"
- + ""
- + "<li>new_file(sibling_file, filename): Creates a file object in the same "
- + "directory as the given sibling file.</li>"
- + ""
- + "<li>new_file(file_root, sibling_file, suffix): Creates a file object with same "
- + "base name of the sibling_file but with different given suffix, under the given "
- + "file root.</li></ul> <br>"
+ "DEPRECATED. Use <a"
+ + " href=\"../builtins/actions.html#declare_file\">ctx.actions.declare_file</a>."
+ + " <br>Creates a file object. There are four possible signatures to this"
+ + " method:<br><ul><li>new_file(filename): Creates a file object with the given"
+ + " filename in the current package.</li><li>new_file(file_root, filename): Creates a"
+ + " file object with the given filename under the given file root.</li>"
+ + "<li>new_file(sibling_file, filename): Creates a file object in the same directory"
+ + " as the given sibling file.</li><li>new_file(file_root, sibling_file, suffix):"
+ + " Creates a file object with same base name of the sibling_file but with different"
+ + " given suffix, under the given file root.</li></ul> <br>"
+ DOC_NEW_FILE_TAIL,
parameters = {
@Param(
@@ -405,19 +402,16 @@
@StarlarkMethod(
name = "expand_make_variables",
doc =
- "<b>Deprecated.</b> Use <a href=\"ctx.html#var\">ctx.var</a> to access the variables "
- + "instead.<br>Returns a string after expanding all references to \"Make "
- + "variables\". The "
- + "variables must have the following format: <code>$(VAR_NAME)</code>. Also, "
- + "<code>$$VAR_NAME</code> expands to <code>$VAR_NAME</code>. "
- + "Examples:"
- + "<pre class=language-python>\n"
- + "ctx.expand_make_variables(\"cmd\", \"$(MY_VAR)\", {\"MY_VAR\": \"Hi\"}) "
- + "# == \"Hi\"\n"
+ "<b>Deprecated.</b> Use <a href=\"../builtins/ctx.html#var\">ctx.var</a> to access the"
+ + " variables instead.<br>Returns a string after expanding all references to \"Make"
+ + " variables\". The variables must have the following format:"
+ + " <code>$(VAR_NAME)</code>. Also, <code>$$VAR_NAME</code> expands to"
+ + " <code>$VAR_NAME</code>. Examples:<pre class=language-python>\n"
+ + "ctx.expand_make_variables(\"cmd\", \"$(MY_VAR)\", {\"MY_VAR\": \"Hi\"}) # =="
+ + " \"Hi\"\n"
+ "ctx.expand_make_variables(\"cmd\", \"$$PWD\", {}) # == \"$PWD\"\n"
- + "</pre>"
- + "Additional variables may come from other places, such as configurations. Note "
- + "that this function is experimental.",
+ + "</pre>Additional variables may come from other places, such as configurations."
+ + " Note that this function is experimental.",
parameters = {
@Param(
name = "attribute_name",
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkRuleFunctionsApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkRuleFunctionsApi.java
index 290a1e8..6dedd38 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkRuleFunctionsApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkRuleFunctionsApi.java
@@ -36,29 +36,26 @@
* functions.
*/
@GlobalMethods(environment = Environment.BZL)
-public interface StarlarkRuleFunctionsApi<FileApiT extends FileApi> {
+public interface StarlarkRuleFunctionsApi {
String EXEC_COMPATIBLE_WITH_PARAM = "exec_compatible_with";
String TOOLCHAINS_PARAM = "toolchains";
String PROVIDES_DOC =
- "A list of providers that the implementation function must return."
- + ""
- + "<p>It is an error if the implementation function omits any of the types of providers "
- + "listed here from its return value. However, the implementation function may return "
- + "additional providers not listed here."
- + ""
- + "<p>Each element of the list is an <code>*Info</code> object returned by "
- + "<a href='globals.html#provider'><code>provider()</code></a>, except that a legacy "
- + "provider is represented by its string name instead."
- + ""
- + "When a target of the rule is used as a dependency for a target that declares a "
- + "required provider, it is not necessary to specify that provider here. It is enough "
- + "that the implementation function returns it. However, it is considered best "
- + "practice to specify it, even though this is not required. The "
- + "<a href='globals#aspect.required_providers'><code>required_providers</code></a> field "
- + "of an <a href='globals.html#aspect'>aspect</a> does, however, require that providers "
- + "are specified here.";
+ "A list of providers that the implementation function must return." //
+ + "<p>It is an error if the implementation function omits any of the types of providers"
+ + " listed here from its return value. However, the implementation function may return"
+ + " additional providers not listed here." //
+ + "<p>Each element of the list is an <code>*Info</code> object returned by <a"
+ + " href='../globals/bzl.html#provider'><code>provider()</code></a>, except that a legacy"
+ + " provider is represented by its string name instead.When a target of the rule is used"
+ + " as a dependency for a target that declares a required provider, it is not necessary"
+ + " to specify that provider here. It is enough that the implementation function returns"
+ + " it. However, it is considered best practice to specify it, even though this is not"
+ + " required. The <a"
+ + " href='../globals/bzl.html#aspect.required_providers'><code>required_providers</code></a>"
+ + " field of an <a href='../globals/bzl.html#aspect'>aspect</a> does, however, require"
+ + " that providers are specified here.";
@StarlarkMethod(
name = "provider",
@@ -76,10 +73,10 @@
+ " ..." //
+ "</pre><p>See <a href='https://bazel.build/extending/rules#providers'>Rules"
+ " (Providers)</a> for a comprehensive guide on how to use providers." //
- + "<p>Returns a <a href='Provider.html#Provider'><code>Provider</code></a> callable "
- + "value if <code>init</code> is not specified." //
+ + "<p>Returns a <a href='../builtins/Provider.html'><code>Provider</code></a>"
+ + " callable value if <code>init</code> is not specified." //
+ "<p>If <code>init</code> is specified, returns a tuple of 2 elements: a <a"
- + " href='Provider.html#Provider'><code>Provider</code></a> callable value and a"
+ + " href='../builtins/Provider.html'><code>Provider</code></a> callable value and a"
+ " <em>raw constructor</em> callable value. See <a"
+ " href='https://bazel.build/extending/rules#custom_initialization_of_providers'>"
+ " Rules (Custom initialization of custom providers)</a> and the discussion of the"
@@ -165,8 +162,9 @@
+ "<p>NB: the above steps imply that an error occurs if <code>*args</code> or"
+ " <code>**kwargs</code> does not match <code>init</code>'s signature, or the"
+ " evaluation of <code>init</code>'s body fails (perhaps intentionally via a"
- + " call to <a href=\"#fail\"><code>fail()</code></a>), or if the return value"
- + " of <code>init</code> is not a dictionary with the expected schema." //
+ + " call to <a href=\"../globals/all.html#fail\"><code>fail()</code></a>), or"
+ + " if the return value of <code>init</code> is not a dictionary with the"
+ + " expected schema." //
+ "<p>In this way, the <code>init</code> callback generalizes normal provider"
+ " construction by allowing positional arguments and arbitrary logic for"
+ " preprocessing and validation. It does <em>not</em> enable circumventing the"
@@ -207,10 +205,10 @@
name = "implementation",
named = true,
doc =
- "the Starlark function implementing this rule, must have exactly one parameter: "
- + "<a href=\"ctx.html\">ctx</a>. The function is called during the analysis "
- + "phase for each instance of the rule. It can access the attributes "
- + "provided by the user. It must create actions to generate all the declared "
+ "the Starlark function implementing this rule, must have exactly one parameter: <a"
+ + " href=\"../builtins/ctx.html\">ctx</a>. The function is called during the"
+ + " analysis phase for each instance of the rule. It can access the attributes"
+ + " provided by the user. It must create actions to generate all the declared "
+ "outputs."),
@Param(
name = "test",
@@ -233,15 +231,15 @@
named = true,
defaultValue = "None",
doc =
- "dictionary to declare all the attributes of the rule. It maps from an attribute "
- + "name to an attribute object (see <a href=\"attr.html\">attr</a> module). "
- + "Attributes starting with <code>_</code> are private, and can be used to "
- + "add an implicit dependency on a label. The attribute <code>name</code> is "
- + "implicitly added and must not be specified. Attributes "
- + "<code>visibility</code>, <code>deprecation</code>, <code>tags</code>, "
- + "<code>testonly</code>, and <code>features</code> are implicitly added and "
- + "cannot be overridden. Most rules need only a handful of attributes. To "
- + "limit memory usage, the rule function imposes a cap on the size of attrs."),
+ "dictionary to declare all the attributes of the rule. It maps from an attribute"
+ + " name to an attribute object (see <a href=\"../toplevel/attr.html\">attr</a>"
+ + " module). Attributes starting with <code>_</code> are private, and can be"
+ + " used to add an implicit dependency on a label. The attribute"
+ + " <code>name</code> is implicitly added and must not be specified. Attributes"
+ + " <code>visibility</code>, <code>deprecation</code>, <code>tags</code>,"
+ + " <code>testonly</code>, and <code>features</code> are implicitly added and"
+ + " cannot be overridden. Most rules need only a handful of attributes. To"
+ + " limit memory usage, the rule function imposes a cap on the size of attrs."),
// TODO(bazel-team): need to give the types of these builtin attributes
@Param(
name = "outputs",
@@ -258,14 +256,14 @@
"This parameter has been deprecated. Migrate rules to use"
+ " <code>OutputGroupInfo</code> or <code>attr.output</code> instead. <p>A"
+ " schema for defining predeclared outputs. Unlike <a"
- + " href='attr.html#output'><code>output</code></a> and <a"
- + " href='attr.html#output_list'><code>output_list</code></a> attributes, the"
- + " user does not specify the labels for these files. See the <a"
- + " href='https://bazel.build/extending/rules#files'>Rules page</a> for more on"
- + " predeclared outputs.<p>The value of this argument is either a dictionary or"
- + " a callback function that produces a dictionary. The callback works similar"
- + " to computed dependency attributes: The function's parameter names are"
- + " matched against the rule's attributes, so for example if you pass"
+ + " href='../toplevel/attr.html#output'><code>output</code></a> and <a"
+ + " href='../toplevel/attr.html#output_list'><code>output_list</code></a>"
+ + " attributes, the user does not specify the labels for these files. See the"
+ + " <a href='https://bazel.build/extending/rules#files'>Rules page</a> for more"
+ + " on predeclared outputs.<p>The value of this argument is either a dictionary"
+ + " or a callback function that produces a dictionary. The callback works"
+ + " similar to computed dependency attributes: The function's parameter names"
+ + " are matched against the rule's attributes, so for example if you pass"
+ " <code>outputs = _my_func</code> with the definition <code>def"
+ " _my_func(srcs, deps): ...</code>, the function has access to the attributes"
+ " <code>srcs</code> and <code>deps</code>. Whether the dictionary is"
@@ -274,10 +272,10 @@
+ " identifier and the value is a string template that determines the output's"
+ " label. In the rule's implementation function, the identifier becomes the"
+ " field name used to access the output's <a"
- + " href='File.html'><code>File</code></a> in <a"
- + " href='ctx.html#outputs'><code>ctx.outputs</code></a>. The output's label"
- + " has the same package as the rule, and the part after the package is"
- + " produced by substituting each placeholder of the form"
+ + " href='../builtins/File.html'><code>File</code></a> in <a"
+ + " href='../builtins/ctx.html#outputs'><code>ctx.outputs</code></a>. The"
+ + " output's label has the same package as the rule, and the part after the"
+ + " package is produced by substituting each placeholder of the form"
+ " <code>\"%{ATTR}\"</code> with a string formed from the value of the"
+ " attribute <code>ATTR</code>:<ul><li>String-typed attributes are substituted"
+ " verbatim.<li>Label-typed attributes become the part of the label after the"
@@ -337,14 +335,12 @@
named = true,
defaultValue = "False",
doc =
- "<i>(Experimental)</i><br/><br/>"
- + "If true, this rule will expose its actions for inspection by rules that "
- + "depend on it via an <a href=\"globals.html#Actions\">Actions</a> "
- + "provider. The provider is also available to the rule itself by calling "
- + "<a href=\"ctx.html#created_actions\">ctx.created_actions()</a>."
- + "<br/><br/>"
- + "This should only be used for testing the analysis-time behavior of "
- + "Starlark rules. This flag may be removed in the future."),
+ "<i>(Experimental)</i><br/><br/>If true, this rule will expose its actions for"
+ + " inspection by rules that depend on it via an <code>Actions</code> provider."
+ + " The provider is also available to the rule itself by calling <a"
+ + " href=\"../builtins/ctx.html#created_actions\">ctx.created_actions()</a>."
+ + "<br/><br/>This should only be used for testing the analysis-time behavior of"
+ + " Starlark rules. This flag may be removed in the future."),
@Param(
name = TOOLCHAINS_PARAM,
allowedTypes = {@ParamType(type = Sequence.class, generic1 = Object.class)},
@@ -405,7 +401,7 @@
+ " This supersedes the value of <code>test</code></li> <li>The rule"
+ " implementation function may not register actions. Instead, it must register"
+ " a pass/fail result via providing <a"
- + " href='AnalysisTestResultInfo.html'>AnalysisTestResultInfo</a>.</li></ul>"),
+ + " href='../providers/AnalysisTestResultInfo.html'>AnalysisTestResultInfo</a>.</li></ul>"),
@Param(
name = "build_setting",
allowedTypes = {
@@ -416,12 +412,12 @@
named = true,
positional = false,
doc =
- "If set, describes what kind of "
- + "<a href = '${link config#user-defined-build-settings}'><code>build "
- + "setting</code></a> this rule is. See the "
- + "<a href='config.html'><code>config</code></a> module. If this is "
- + "set, a mandatory attribute named \"build_setting_default\" is automatically "
- + "added to this rule, with a type corresponding to the value passed in here."),
+ "If set, describes what kind of <a href='${link"
+ + " config#user-defined-build-settings}'><code>build setting</code></a> this"
+ + " rule is. See the <a href='../toplevel/config.html'><code>config</code></a>"
+ + " module. If this is set, a mandatory attribute named"
+ + " \"build_setting_default\" is automatically added to this rule, with a type"
+ + " corresponding to the value passed in here."),
@Param(
name = "cfg",
defaultValue = "None",
@@ -441,7 +437,7 @@
positional = false,
doc =
"Dict of execution group name (string) to <a"
- + " href='globals.html#exec_group'><code>exec_group</code>s</a>. If set,"
+ + " href='../globals/bzl.html#exec_group'><code>exec_group</code>s</a>. If set,"
+ " allows rules to run actions on multiple execution platforms within a"
+ " single target. See <a href='${link exec-groups}'>execution groups"
+ " documentation</a> for more info."),
@@ -515,12 +511,12 @@
name = "implementation",
named = true,
doc =
- "A Starlark function that implements this aspect, with exactly two parameters: "
- + "<a href=\"Target.html\">Target</a> (the target to which the aspect is "
- + "applied) and <a href=\"ctx.html\">ctx</a> (the rule context which the "
- + "target is created from). Attributes of the target are available via the "
- + "<code>ctx.rule</code> field. This function is evaluated during the "
- + "analysis phase for each application of an aspect to a target."),
+ "A Starlark function that implements this aspect, with exactly two parameters: <a"
+ + " href=\"../builtins/Target.html\">Target</a> (the target to which the aspect"
+ + " is applied) and <a href=\"../builtins/ctx.html\">ctx</a> (the rule context"
+ + " which the target is created from). Attributes of the target are available"
+ + " via the <code>ctx.rule</code> field. This function is evaluated during the"
+ + " analysis phase for each application of an aspect to a target."),
@Param(
name = "attr_aspects",
allowedTypes = {@ParamType(type = Sequence.class, generic1 = String.class)},
@@ -541,19 +537,17 @@
named = true,
defaultValue = "None",
doc =
- "A dictionary declaring all the attributes of the aspect. It maps from an "
- + "attribute name to an attribute object, like `attr.label` or `attr.string` "
- + "(see <a href=\"attr.html\">attr</a> module). Aspect attributes are "
- + "available to implementation function as fields of <code>ctx</code> "
- + "parameter. "
- + ""
- + "<p>Implicit attributes starting with <code>_</code> must have default "
- + "values, and have type <code>label</code> or <code>label_list</code>. "
- + ""
- + "<p>Explicit attributes must have type <code>string</code>, and must use "
- + "the <code>values</code> restriction. Explicit attributes restrict the "
- + "aspect to only be used with rules that have attributes of the same "
- + "name, type, and valid values according to the restriction."),
+ "A dictionary declaring all the attributes of the aspect. It maps from an attribute"
+ + " name to an attribute object, like `attr.label` or `attr.string` (see <a"
+ + " href=\"../toplevel/attr.html\">attr</a> module). Aspect attributes are"
+ + " available to implementation function as fields of <code>ctx</code>"
+ + " parameter. <p>Implicit attributes starting with <code>_</code> must have"
+ + " default values, and have type <code>label</code> or"
+ + " <code>label_list</code>. <p>Explicit attributes must have type"
+ + " <code>string</code>, and must use the <code>values</code> restriction."
+ + " Explicit attributes restrict the aspect to only be used with rules that"
+ + " have attributes of the same name, type, and valid values according to the"
+ + " restriction."),
@Param(
name = "required_providers",
named = true,
@@ -686,7 +680,7 @@
positional = false,
doc =
"Dict of execution group name (string) to <a"
- + " href='globals.html#exec_group'><code>exec_group</code>s</a>. If set,"
+ + " href='../globals/bzl.html#exec_group'><code>exec_group</code>s</a>. If set,"
+ " allows aspects to run actions on multiple execution platforms within a"
+ " single instance. See <a href='${link exec-groups}'>execution groups"
+ " documentation</a> for more info.")
@@ -716,10 +710,9 @@
doc =
"Converts a label string into a <code>Label</code> object, in the context of the package"
+ " where the calling <code>.bzl</code> source file lives. If the given value is"
- + " already a <code>Label</code>, it is returned unchanged."
- + "<p>For macros, a related function,"
- + " <code><a"
- + " href='native#package_relative_label'>native.package_relative_label()</a></code>,"
+ + " already a <code>Label</code>, it is returned unchanged.<p>For macros, a related"
+ + " function, <code><a"
+ + " href='../toplevel/native.html#package_relative_label'>native.package_relative_label()</a></code>,"
+ " converts the input into a <code>Label</code> in the context of the package"
+ " currently being constructed. Use that function to mimic the string-to-label"
+ " conversion that is automatically done by label-valued rule attributes.",
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/TemplateDictApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/TemplateDictApi.java
index e7315c4..8004c6e 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/TemplateDictApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/TemplateDictApi.java
@@ -62,7 +62,7 @@
doc =
"A delimiter string used to join together the strings obtained from applying "
+ "<code>map_each</code>, in the same manner as "
- + "<a href='string.html#join'><code>string.join()</code></a>."),
+ + "<a href='../core/string.html#join'><code>string.join()</code></a>."),
@Param(
name = "map_each",
allowedTypes = {
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/ApplePlatformApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/ApplePlatformApi.java
index 15908e1..6a06a5a 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/ApplePlatformApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/ApplePlatformApi.java
@@ -27,20 +27,19 @@
"Corresponds to Xcode's notion of a platform as would be found in"
+ " <code>Xcode.app/Contents/Developer/Platforms</code>. Each platform represents an"
+ " Apple platform type (such as iOS or tvOS) combined with one or more related CPU"
- + " architectures. For example, the iOS simulator platform supports"
- + " <code>x86_64</code> and <code>i386</code> architectures.<p>Specific instances of"
- + " this type can be retrieved from the fields of the <a"
- + " href='apple_common.html#platform'>apple_common.platform</a> struct:<br><ul>"
- + "<li><code>apple_common.platform.ios_device</code></li>"
+ + " architectures. For example, the iOS simulator platform supports <code>x86_64</code>"
+ + " and <code>i386</code> architectures.<p>Specific instances of this type can be"
+ + " retrieved from the fields of the <a"
+ + " href='../toplevel/apple_common.html#platform'>apple_common.platform</a>"
+ + " struct:<br><ul><li><code>apple_common.platform.ios_device</code></li>"
+ "<li><code>apple_common.platform.ios_simulator</code></li>"
+ "<li><code>apple_common.platform.macos</code></li>"
+ "<li><code>apple_common.platform.tvos_device</code></li>"
+ "<li><code>apple_common.platform.tvos_simulator</code></li>"
- + "<li><code>apple_common.platform.watchos_device</code></li>"
- + "<li><code>apple_common.platform.watchos_simulator</code></li></ul><p>More commonly,"
- + " however, the <a href='apple.html'>apple</a> configuration fragment has"
- + " fields/methods that allow rules to determine the platform for which a target is"
- + " being built.<p>Example:<br><pre class='language-python'>\n"
+ + "<li><code>apple_common.platform.watchos_device</code></li><li><code>apple_common.platform.watchos_simulator</code></li></ul><p>More"
+ + " commonly, however, the <a href='../fragments/apple.html'>apple</a> configuration"
+ + " fragment has fields/methods that allow rules to determine the platform for which a"
+ + " target is being built.<p>Example:<br><pre class='language-python'>\n"
+ "p = apple_common.platform.ios_device\n"
+ "print(p.name_in_plist) # 'iPhoneOS'\n"
+ "</pre>")
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/ApplePlatformTypeApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/ApplePlatformTypeApi.java
index e110ad9..8ad811e 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/ApplePlatformTypeApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/ApplePlatformTypeApi.java
@@ -27,13 +27,12 @@
+ " distinct from a \"platform\", which is the platform type combined with one or more"
+ " CPU architectures.<p>Specific instances of this type can be retrieved by accessing"
+ " the fields of the <a"
- + " href='apple_common.html#platform_type'>apple_common.platform_type</a>:<br><ul>"
+ + " href='../toplevel/apple_common.html#platform_type'>apple_common.platform_type</a>:<br><ul>"
+ "<li><code>apple_common.platform_type.ios</code></li>"
+ "<li><code>apple_common.platform_type.macos</code></li>"
- + "<li><code>apple_common.platform_type.tvos</code></li>"
- + "<li><code>apple_common.platform_type.watchos</code></li></ul><p>Likewise, the"
- + " platform type of an existing platform value can be retrieved using its"
+ + "<li><code>apple_common.platform_type.tvos</code></li><li><code>apple_common.platform_type.watchos</code></li></ul><p>Likewise,"
+ + " the platform type of an existing platform value can be retrieved using its"
+ " <code>platform_type</code> field.<p>Platform types can be converted to a lowercase"
+ " string (e.g., <code>ios</code> or <code>macos</code>) using the <a"
- + " href='globals.html#str'>str</a> function.")
+ + " href='../globals/all.html#str'>str</a> function.")
public interface ApplePlatformTypeApi extends StarlarkValue {}
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/AppleToolchainApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/AppleToolchainApi.java
index e40ba48..db5f3a1 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/AppleToolchainApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/AppleToolchainApi.java
@@ -23,7 +23,7 @@
/** Interface for a utility module involving the Apple toolchain. */
@StarlarkBuiltin(
name = "apple_toolchain",
- category = DocCategory.TOP_LEVEL_MODULE,
+ category = DocCategory.BUILTIN,
doc = "Utilities for resolving items from the Apple toolchain.")
public interface AppleToolchainApi<AppleConfigurationApiT extends AppleConfigurationApi<?>>
extends StarlarkValue {
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/config/ConfigGlobalLibraryApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/config/ConfigGlobalLibraryApi.java
index 4b3fcfe..df710d5 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/config/ConfigGlobalLibraryApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/config/ConfigGlobalLibraryApi.java
@@ -106,8 +106,9 @@
+ " <code>analysis_test = True</code>. Such rules are restricted in capabilities (for"
+ " example, the size of their dependency tree is limited), so transitions created"
+ " using this function are limited in potential scope as compared to transitions"
- + " created using <a href=\"transition.html\">transition</a>. <p>This function is"
- + " primarily designed to facilitate the <a"
+ + " created using <a"
+ + " href=\"../builtins/transition.html\"><code>transition()</code></a>. <p>This"
+ + " function is primarily designed to facilitate the <a"
+ " href=\"https://bazel.build/rules/testing\">Analysis Test Framework</a> core"
+ " library. See its documentation (or its implementation) for best practices.",
parameters = {
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/core/ProviderApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/core/ProviderApi.java
index 986f64f..bc192ff 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/core/ProviderApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/core/ProviderApi.java
@@ -33,12 +33,12 @@
+ " Note: Some providers, defined internally, do not allow instance creation"
+ " </li>"
+ " <li>It is a <i>key</i> to access a provider instance on a"
- + " <a href=\"Target.html\">Target</a>"
+ + " <a href=\"../builtins/Target.html\">Target</a>"
+ "<pre class=\"language-python\">DataInfo = provider()\n"
+ "def _rule_impl(ctx)\n"
+ " ... ctx.attr.dep[DataInfo]</pre>"
+ " </li>"
+ " </ul>"
+ "Create a new <code>Provider</code> using the "
- + "<a href=\"globals.html#provider\">provider</a> function.")
+ + "<a href=\"../globals/bzl.html#provider\">provider</a> function.")
public interface ProviderApi extends StarlarkValue {}
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/core/TransitiveInfoCollectionApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/core/TransitiveInfoCollectionApi.java
index 4a7c7f3..3b7485c 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/core/TransitiveInfoCollectionApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/core/TransitiveInfoCollectionApi.java
@@ -24,25 +24,26 @@
category = DocCategory.BUILTIN,
doc =
"The BUILD target for a dependency. Appears in the fields of <code><a"
- + " href='ctx.html#attr'>ctx.attr</a></code> corresponding to <a"
+ + " href='../builtins/ctx.html#attr'>ctx.attr</a></code> corresponding to <a"
+ " href='https://bazel.build/extending/rules#dependency_attributes'>dependency"
- + " attributes</a> (<code><a href='attr.html#label'>label</a></code> or <code><a"
- + " href='attr.html#label_list'>label_list</a></code>). Has the following fields:\n"
+ + " attributes</a> (<code><a href='../toplevel/attr.html#label'>label</a></code> or"
+ + " <code><a href='../toplevel/attr.html#label_list'>label_list</a></code>). Has the"
+ + " following fields:\n"
//
+ "<ul>\n" //
+ "<li><h3 id='modules.Target.label'>label</h3>\n" //
- + "<code><a href='Label.html'>Label</a> Target.label</code><br/>\n" //
+ + "<code><a href='../builtins/Label.html'>Label</a> Target.label</code><br/>\n" //
+ "The identifier of the target.</li>\n" //
//
+ "<li><h3 id='modules.Target.files'>files</h3>\n" //
- + "<code><a href='depset.html'>depset</a> Target.files </code><br/>\n" //
- + "The set of <code><a href='File.html'>File</a></code>s in the default outputs for "
- + "this target. Equivalent to <code><a href='DefaultInfo.html#files'>"
- + "target[DefaultInfo].files</a></code>.</li>\n" //
+ + "<code><a href='../builtins/depset.html'>depset</a> Target.files </code><br/>\n" //
+ + "The set of <code><a href='../builtins/File.html'>File</a></code>s in the default"
+ + " outputs for this target. Equivalent to <code><a"
+ + " href='../providers/DefaultInfo.html#files'>target[DefaultInfo].files</a></code>.</li>\n" //
//
+ "<li><h3 id='modules.Target.aspect_ids'>aspect_ids</h3>\n" //
- + "<code><a href='list.html'>list</a> Target.aspect_ids </code><br/>\n" //
- + "The list of <code><a href='ctx.html#aspect_ids'>aspect_ids</a></code> "
+ + "<code><a href='../core/list.html'>list</a> Target.aspect_ids </code><br/>\n" //
+ + "The list of <code><a href='../builtins/ctx.html#aspect_ids'>aspect_ids</a></code> "
+ "applied to this target.</li>\n" //
//
+ "<li><h3 id='modules.Target.providers'>Providers</h3>\n" //
@@ -52,9 +53,9 @@
+ " the <code>in</code> operator (<code>SomeInfo in target</code>).<br/>\n" //
+ "<br/>\n" //
+ "If the rule's implementation function returns a <code><a"
- + " href='struct.html'>struct</a></code> instead of a list of <code><a"
- + " href='Provider.html'>Provider</a></code> instances, the struct's fields can be"
- + " accessed via the corresponding fields of the <code>Target</code>"
+ + " href='../builtins/struct.html'>struct</a></code> instead of a list of <code><a"
+ + " href='../builtins/Provider.html'>Provider</a></code> instances, the struct's fields"
+ + " can be accessed via the corresponding fields of the <code>Target</code>"
+ " (<code>target.some_legacy_info</code>). This behavior <a"
+ " href='https://bazel.build/extending/rules#migrating_from_legacy_providers'>is"
+ " deprecated</a>.</li>\n" //
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcCompilationContextApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcCompilationContextApi.java
index fd841e3..93a866e 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcCompilationContextApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcCompilationContextApi.java
@@ -31,7 +31,7 @@
*/
@StarlarkBuiltin(
name = "CompilationContext",
- category = DocCategory.PROVIDER,
+ category = DocCategory.BUILTIN,
doc =
"Immutable store of information needed for C++ compilation that is aggregated across "
+ "dependencies.")
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcLinkingOutputsApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcLinkingOutputsApi.java
index eff698b..e412cc3 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcLinkingOutputsApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcLinkingOutputsApi.java
@@ -37,9 +37,7 @@
name = "library_to_link",
structField = true,
allowReturnNones = true,
- doc =
- "<a href='LibraryToLink.html'><code>LibraryToLink</code></a> for including these outputs "
- + "in further linking.",
+ doc = "<code>LibraryToLink</code> for including these outputs in further linking.",
documented = true)
@Nullable
LibraryToLinkApi<FileT, LtoBackendArtifactsT> getLibraryToLink();
@@ -48,7 +46,7 @@
name = "executable",
structField = true,
allowReturnNones = true,
- doc = "<a href='File.html'><code>File</code></a> object representing the linked executable.",
+ doc = "Represents the linked executable.",
documented = true)
@Nullable
FileT getExecutable();
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CppConfigurationApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CppConfigurationApi.java
index 8026fcf..5054a6c 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CppConfigurationApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CppConfigurationApi.java
@@ -99,7 +99,7 @@
doc =
"Returns label pointed to by <a href=\"${link user-manual#flag--custom_malloc}\">"
+ "<code>--custom_malloc</code></a> option. Can be accessed with"
- + " <a href=\"globals.html#configuration_field\"><code>configuration_field"
+ + " <a href=\"../globals/bzl.html#configuration_field\"><code>configuration_field"
+ "</code></a>:<br/>"
+ "<pre>attr.label(<br/>"
+ " default = configuration_field(<br/>"
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaCommonApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaCommonApi.java
index b362246..569619d 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaCommonApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaCommonApi.java
@@ -321,7 +321,7 @@
"Runs ijar on a jar, stripping it of its method bodies. This helps reduce rebuilding "
+ "of dependent jars during any recompiles consisting only of simple changes to "
+ "method implementations. The return value is typically passed to "
- + "<code><a class=\"anchor\" href=\"JavaInfo.html\">"
+ + "<code><a class=\"anchor\" href=\"../providers/JavaInfo.html\">"
+ "JavaInfo</a>#compile_jar</code>.",
parameters = {
@Param(name = "actions", named = true, doc = "ctx.actions"),
@@ -366,10 +366,10 @@
doc =
"Stamps a jar with a target label for <code>add_dep</code> support. "
+ "The return value is typically passed to "
- + "<code><a class=\"anchor\" href=\"JavaInfo.html\">"
+ + "<code><a class=\"anchor\" href=\"../providers/JavaInfo.html\">"
+ "JavaInfo</a>#compile_jar</code>. "
+ "Prefer to use "
- + "<code><a class=\"anchor\" href=\"java_common.html#run_ijar\">run_ijar</a></code> "
+ + "<code><a class=\"anchor\" href=\"#run_ijar\">run_ijar</a></code> "
+ "when possible.",
parameters = {
@Param(name = "actions", named = true, doc = "ctx.actions"),
@@ -401,7 +401,7 @@
doc =
"Packs sources and source jars into a single source jar file. "
+ "The return value is typically passed to"
- + "<p><code><a class=\"anchor\" href=\"JavaInfo.html\">"
+ + "<p><code><a class=\"anchor\" href=\"../providers/JavaInfo.html\">"
+ "JavaInfo</a>#source_jar</code></p>."
+ "At least one of parameters output_jar or output_source_jar is required.",
parameters = {
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaInfoApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaInfoApi.java
index f9ccc38..271de29 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaInfoApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaInfoApi.java
@@ -71,16 +71,16 @@
"Returns the regular, full compile time Jars required by this target directly. They can"
+ " be <ul><li> the corresponding regular Jars of the interface Jars returned by"
+ " <code><a class=\"anchor\""
- + " href=\"JavaInfo.html#compile_jars\">JavaInfo.compile_jars</a></code></li><li>"
+ + " href=\"#compile_jars\">JavaInfo.compile_jars</a></code></li><li>"
+ " the regular (full) Jars returned by <code><a class=\"anchor\""
- + " href=\"JavaInfo.html#compile_jars\">JavaInfo.compile_jars</a></code></li></ul>"
+ + " href=\"#compile_jars\">JavaInfo.compile_jars</a></code></li></ul>"
+ "<p>Note: <code><a class=\"anchor\""
- + " href=\"JavaInfo.html#compile_jars\">JavaInfo.compile_jars</a></code> can return"
+ + " href=\"#compile_jars\">JavaInfo.compile_jars</a></code> can return"
+ " a mix of interface Jars and regular Jars.<p>Only use this method if interface"
+ " Jars don't work with your rule set(s) (e.g. some Scala targets) If you're"
+ " working with Java-only targets it's preferable to use interface Jars via"
+ " <code><a class=\"anchor\""
- + " href=\"JavaInfo.html#compile_jars\">JavaInfo.compile_jars</a></code></li>",
+ + " href=\"#compile_jars\">JavaInfo.compile_jars</a></code></li>",
structField = true)
Depset getFullCompileTimeJars();
@@ -133,7 +133,7 @@
name = "transitive_deps",
doc =
"Deprecated: Please use <code><a class=\"anchor\" "
- + "href=\"JavaInfo.html#transitive_compile_time_jars\">JavaInfo.transitive_compile_time_jars</a></code>"
+ + "href=\"#transitive_compile_time_jars\">JavaInfo.transitive_compile_time_jars</a></code>"
+ " instead. It returns the same value.",
structField = true)
Depset /*<FileT>*/ getTransitiveDeps();
@@ -142,7 +142,7 @@
name = "transitive_runtime_deps",
doc =
"Deprecated: please use <code><a class=\"anchor\""
- + " href=\"JavaInfo.html#transitive_runtime_jars\">JavaInfo.transitive_runtime_jars"
+ + " href=\"#transitive_runtime_jars\">JavaInfo.transitive_runtime_jars"
+ "</a></code> instead. It returns the same value",
structField = true)
Depset /*<FileT>*/ getTransitiveRuntimeDeps();
@@ -198,10 +198,10 @@
doc =
"A jar that is added as the compile-time dependency in lieu of "
+ "<code>output_jar</code>. Typically this is the ijar produced by "
- + "<code><a class=\"anchor\" href=\"java_common.html#run_ijar\">"
+ + "<code><a class=\"anchor\" href=\"../toplevel/java_common.html#run_ijar\">"
+ "run_ijar</a></code>. "
+ "If you cannot use ijar, consider instead using the output of "
- + "<code><a class=\"anchor\" href=\"java_common.html#stamp_jar\">"
+ + "<code><a class=\"anchor\" href=\"../toplevel/java_common.html#stamp_jar\">"
+ "stamp_ijar</a></code>. If you do not wish to use either, "
+ "you can simply pass <code>output_jar</code>. "
+ "There are a couple of special cases when this parameter may be set to "
@@ -216,9 +216,10 @@
named = true,
defaultValue = "None",
doc =
- "The source jar that was used to create the output jar. "
- + "Use <code><a class=\"anchor\" href=\"java_common.html#pack_sources\">"
- + "pack_sources</a></code> to produce this source jar."),
+ "The source jar that was used to create the output jar. Use <code><a"
+ + " class=\"anchor\""
+ + " href=\"../toplevel/java_common.html#pack_sources\">pack_sources</a>"
+ + "</code> to produce this source jar."),
@Param(
name = "compile_jdeps",
allowedTypes = {
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/objc/AppleCommonApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/objc/AppleCommonApi.java
index 418a077..7932e1f 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/objc/AppleCommonApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/objc/AppleCommonApi.java
@@ -66,10 +66,15 @@
name = "platform_type",
doc =
"An enum-like struct that contains the following fields corresponding to Apple platform "
- + "types:<br><ul><li><code>ios</code></li><li><code>macos</code></li>"
- + "<li><code>tvos</code></li><li><code>watchos</code></li></ul><p>These values can"
- + " be passed to methods that expect a platform type, like the 'apple' configuration"
- + " fragment's <a href='apple.html#multi_arch_platform'>multi_arch_platform</a>"
+ + "types:<br><ul>" //
+ + "<li><code>ios</code></li>" //
+ + "<li><code>macos</code></li>" //
+ + "<li><code>tvos</code></li>" //
+ + "<li><code>watchos</code></li>" //
+ + "</ul><p>" //
+ + "These values can be passed to methods that expect a platform type, like the"
+ + " 'apple' configuration fragment's <a"
+ + " href='../fragments/apple.html#multi_arch_platform'>multi_arch_platform</a>"
+ " method.<p>Example:<p><pre class='language-python'>\n"
+ "ctx.fragments.apple.multi_arch_platform(apple_common.platform_type.ios)\n"
+ "</pre>",
@@ -87,17 +92,17 @@
name = "platform",
doc =
"An enum-like struct that contains the following fields corresponding to Apple "
- + "platforms:<br><ul>"
- + "<li><code>ios_device</code></li>"
- + "<li><code>ios_simulator</code></li>"
- + "<li><code>macos</code></li>"
- + "<li><code>tvos_device</code></li>"
- + "<li><code>tvos_simulator</code></li>"
- + "<li><code>watchos_device</code></li>"
- + "<li><code>watchos_simulator</code></li>"
- + "</ul><p>"
+ + "platforms:<br><ul>" //
+ + "<li><code>ios_device</code></li>" //
+ + "<li><code>ios_simulator</code></li>" //
+ + "<li><code>macos</code></li>" //
+ + "<li><code>tvos_device</code></li>" //
+ + "<li><code>tvos_simulator</code></li>" //
+ + "<li><code>watchos_device</code></li>" //
+ + "<li><code>watchos_simulator</code></li>" //
+ + "</ul><p>" //
+ "These values can be passed to methods that expect a platform, like "
- + "<a href='XcodeVersionConfig.html#sdk_version_for_platform'>"
+ + "<a href='../providers/XcodeVersionConfig.html#sdk_version_for_platform'>"
+ "XcodeVersionConfig.sdk_version_for_platform</a>.",
structField = true)
StructApi getPlatformStruct();
@@ -177,10 +182,10 @@
@StarlarkMethod(
name = "apple_host_system_env",
doc =
- "Returns a <a href='dict.html'>dict</a> of environment variables that should be set "
- + "for actions that need to run build tools on an Apple host system, such as the "
- + " version of Xcode that should be used. The keys are variable names and the values "
- + " are their corresponding values.",
+ "Returns a <a href='../core/dict.html'>dict</a> of environment variables that should be"
+ + " set for actions that need to run build tools on an Apple host system, such as the"
+ + " version of Xcode that should be used. The keys are variable names and the values"
+ + " are their corresponding values.",
parameters = {
@Param(
name = "xcode_config",
@@ -427,7 +432,7 @@
@StarlarkMethod(
name = "dotted_version",
- doc = "Creates a new <a href=\"DottedVersion.html\">DottedVersion</a> instance.",
+ doc = "Creates a new <a href=\"../builtins/DottedVersion.html\">DottedVersion</a> instance.",
parameters = {
@Param(name = "version", doc = "The string representation of the DottedVersion.")
})
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/PlatformCommonApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/PlatformCommonApi.java
index cbe266c..d2b1f82 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/PlatformCommonApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/PlatformCommonApi.java
@@ -29,21 +29,24 @@
@StarlarkMethod(
name = "TemplateVariableInfo",
doc =
- "The constructor/key for the <a href='TemplateVariableInfo.html'>"
+ "The constructor/key for the <a href='../providers/TemplateVariableInfo.html'>"
+ "TemplateVariableInfo</a> provider.",
structField = true)
ProviderApi getMakeVariableProvider();
@StarlarkMethod(
name = "ToolchainInfo",
- doc = "The constructor/key for the <a href='ToolchainInfo.html'>ToolchainInfo</a> provider.",
+ doc =
+ "The constructor/key for the <a href='../providers/ToolchainInfo.html'>ToolchainInfo</a>"
+ + " provider.",
structField = true)
ProviderApi getToolchainInfoConstructor();
@StarlarkMethod(
name = "PlatformInfo",
doc =
- "The constructor/key for the <a href='PlatformInfo.html'>PlatformInfo</a> provider."
+ "The constructor/key for the <a href='../providers/PlatformInfo.html'>PlatformInfo</a>"
+ + " provider."
+ PlatformInfoApi.EXPERIMENTAL_WARNING,
structField = true)
ProviderApi getPlatformInfoConstructor();
@@ -51,7 +54,7 @@
@StarlarkMethod(
name = "ConstraintSettingInfo",
doc =
- "The constructor/key for the <a href='ConstraintSettingInfo.html'>"
+ "The constructor/key for the <a href='../providers/ConstraintSettingInfo.html'>"
+ "ConstraintSettingInfo</a> provider."
+ PlatformInfoApi.EXPERIMENTAL_WARNING,
structField = true)
@@ -60,7 +63,7 @@
@StarlarkMethod(
name = "ConstraintValueInfo",
doc =
- "The constructor/key for the <a href='ConstraintValueInfo.html'>"
+ "The constructor/key for the <a href='../providers/ConstraintValueInfo.html'>"
+ "ConstraintValueInfo</a> provider."
+ PlatformInfoApi.EXPERIMENTAL_WARNING,
structField = true)
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/proto/ProtoCommonApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/proto/ProtoCommonApi.java
index 6143696..85b612f 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/proto/ProtoCommonApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/proto/ProtoCommonApi.java
@@ -27,10 +27,8 @@
name = "proto_common",
category = DocCategory.TOP_LEVEL_MODULE,
doc =
- "Utilities for protocol buffers. "
- + "<p>"
- + "Please consider using `load(\"@rules_proto//proto:defs.bzl\", \"proto_common\")` "
- + "to load this symbol from <a href=\"https://github.com/bazelbuild/rules_proto\">"
- + "rules_proto</a>"
+ "Utilities for protocol buffers. <p>Please consider using"
+ + " <code>load(\"@rules_proto//proto:defs.bzl\", \"proto_common\")</code> to load this"
+ + " symbol from <a href=\"https://github.com/bazelbuild/rules_proto\">rules_proto</a>."
+ "</p>")
public interface ProtoCommonApi extends StarlarkValue {}
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/repository/RepositoryModuleApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/repository/RepositoryModuleApi.java
index d1ad2dc..b0aa1b1 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/repository/RepositoryModuleApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/repository/RepositoryModuleApi.java
@@ -47,8 +47,8 @@
name = "implementation",
named = true,
doc =
- "the function that implements this rule. Must have a single parameter,"
- + " <code><a href=\"repository_ctx.html\">repository_ctx</a></code>. The"
+ "the function that implements this rule. Must have a single parameter, <code><a"
+ + " href=\"../builtins/repository_ctx.html\">repository_ctx</a></code>. The"
+ " function is called during the loading phase for each instance of the"
+ " rule."),
@Param(
@@ -60,7 +60,7 @@
defaultValue = "None",
doc =
"dictionary to declare all the attributes of the rule. It maps from an attribute "
- + "name to an attribute object (see <a href=\"attr.html\">attr</a> "
+ + "name to an attribute object (see <a href=\"../toplevel/attr.html\">attr</a> "
+ "module). Attributes starting with <code>_</code> are private, and can be "
+ "used to add an implicit dependency on a label to a file (a repository "
+ "rule cannot depend on a generated artifact). The attribute "
@@ -133,16 +133,16 @@
named = true,
doc =
"The function that implements this module extension. Must take a single parameter,"
- + " <code><a href=\"module_ctx.html\">module_ctx</a></code>. The function is"
- + " called once at the beginning of a build to determine the set of available"
- + " repos."),
+ + " <code><a href=\"../builtins/module_ctx.html\">module_ctx</a></code>. The"
+ + " function is called once at the beginning of a build to determine the set of"
+ + " available repos."),
@Param(
name = "tag_classes",
defaultValue = "{}",
doc =
"A dictionary to declare all the tag classes used by the extension. It maps from"
+ " the name of the tag class to a <code><a"
- + " href=\"tag_class.html\">tag_class</a></code> object.",
+ + " href=\"../builtins/tag_class.html\">tag_class</a></code> object.",
named = true,
positional = false),
@Param(
@@ -174,8 +174,8 @@
named = true,
doc =
"A dictionary to declare all the attributes of this tag class. It maps from an"
- + " attribute name to an attribute object (see <a href=\"attr.html\">attr</a>"
- + " module)."),
+ + " attribute name to an attribute object (see <a"
+ + " href=\"../toplevel/attr.html\">attr</a> module)."),
@Param(
name = "doc",
defaultValue = "''",
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/CoverageCommonApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/CoverageCommonApi.java
index aacd6a8..30a47151 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/CoverageCommonApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/CoverageCommonApi.java
@@ -44,10 +44,10 @@
@StarlarkMethod(
name = "instrumented_files_info",
doc =
- "Creates a new "
- + "<a class=\"anchor\" href=\"InstrumentedFilesInfo.html\">InstrumentedFilesInfo</a> "
- + "instance. Use this provider to communicate coverage-related attributes of the "
- + "current build rule.",
+ "Creates a new <a class=\"anchor\""
+ + " href=\"../providers/InstrumentedFilesInfo.html\">InstrumentedFilesInfo</a>"
+ + " instance. Use this provider to communicate coverage-related attributes of the"
+ + " current build rule.",
parameters = {
@Param(name = "ctx", positional = true, named = true, doc = "The rule context."),
@Param(
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/CoverageConfigurationApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/CoverageConfigurationApi.java
index 5cfaffb..b3388ac 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/CoverageConfigurationApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/CoverageConfigurationApi.java
@@ -38,7 +38,7 @@
+ "#flag--coverage_output_generator\">"
+ "<code>--coverage_output_generator</code></a> option if coverage collection is"
+ " enabled, otherwise returns <code>None</code>. Can be accessed with"
- + " <a href=\"globals.html#configuration_field\"><code>configuration_field"
+ + " <a href=\"../globals/bzl.html#configuration_field\"><code>configuration_field"
+ "</code></a>:<br/>"
+ "<pre>attr.label(<br/>"
+ " default = configuration_field(<br/>"
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/InstrumentedFilesInfoApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/InstrumentedFilesInfoApi.java
index 398673f..dde7e54 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/InstrumentedFilesInfoApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/InstrumentedFilesInfoApi.java
@@ -28,9 +28,8 @@
"Contains information about source files and instrumentation metadata files for rule"
+ " targets matched by <a"
+ " href=\"https://bazel.build/reference/command-line-reference#flag--instrumentation_filter\"><code>--instrumentation_filter</code></a>"
- + " for purposes of <a"
- + " href=\"https://bazel.build/extending/rules#code_coverage\">code coverage"
- + " data collection</a>. When coverage data collection is enabled, a manifest"
+ + " for purposes of <a href=\"https://bazel.build/extending/rules#code_coverage\">code"
+ + " coverage data collection</a>. When coverage data collection is enabled, a manifest"
+ " containing the combined paths in <a"
+ " href=\"#instrumented_files\"><code>instrumented_files</code></a> and <a"
+ " href=\"#metadata_files\"><code>metadata_files</code></a> are passed to the test"
@@ -45,21 +44,21 @@
@StarlarkMethod(
name = "instrumented_files",
doc =
- "<a href=\"depset.html\"><code>depset</code></a> of <a href=\"File.html\"><code>File"
- + "</code></a> objects representing instrumented source files for this target and "
- + "its dependencies.",
+ "<a href=\"../builtins/depset.html\"><code>depset</code></a> of <a"
+ + " href=\"../builtins/File.html\"><code>File</code></a> objects representing"
+ + " instrumented source files for this target and its dependencies.",
structField = true)
Depset getInstrumentedFilesForStarlark();
@StarlarkMethod(
name = "metadata_files",
doc =
- "<a href=\"depset.html\"><code>depset</code></a> of <a href=\"File.html\"><code>File"
- + "</code></a> objects representing coverage metadata files for this target and its "
- + "dependencies. These files contain additional information required to generate "
- + "LCOV-format coverage output after the code is executed, e.g. the "
- + "<code>.gcno</code> files generated when <code>gcc</code> is run with "
- + "<code>-ftest-coverage</code>.",
+ "<a href=\"../builtins/depset.html\"><code>depset</code></a> of <a"
+ + " href=\"../builtins/File.html\"><code>File</code></a> objects representing"
+ + " coverage metadata files for this target and its dependencies. These files contain"
+ + " additional information required to generate LCOV-format coverage output after the"
+ + " code is executed, e.g. the <code>.gcno</code> files generated when"
+ + " <code>gcc</code> is run with <code>-ftest-coverage</code>.",
structField = true)
Depset getInstrumentationMetadataFilesForStarlark();
}
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/TestingModuleApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/TestingModuleApi.java
index 37234c6..0f262d0 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/TestingModuleApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/TestingModuleApi.java
@@ -39,7 +39,9 @@
@StarlarkMethod(
name = "ExecutionInfo",
- doc = "<a href='ExecutionInfo.html'>testing.ExecutionInfo</a> provider key/constructor",
+ doc =
+ "<a href='../providers/ExecutionInfo.html'>testing.ExecutionInfo</a> provider"
+ + " key/constructor",
structField = true)
ExecutionInfoApi.ExecutionInfoApiProvider executionInfo() throws EvalException;
@@ -93,12 +95,13 @@
named = true,
doc =
"The Starlark function implementing this analysis test. It must have exactly one"
- + " parameter: <a href=\"ctx.html\">ctx</a>. The function is called during the"
- + " analysis phase. It can access the attributes declared by <code>attrs</code>"
- + " and populated via <code>attr_values</code>. The implementation function may"
- + " not register actions. Instead, it must register a pass/fail result"
- + " via providing <a"
- + " href='AnalysisTestResultInfo.html'>AnalysisTestResultInfo</a>."),
+ + " parameter: <a href=\"../builtins/ctx.html\">ctx</a>. The function is called"
+ + " during the analysis phase. It can access the attributes declared by"
+ + " <code>attrs</code> and populated via <code>attr_values</code>. The"
+ + " implementation function may not register actions. Instead, it must register"
+ + " a pass/fail result via providing <a"
+ + " href='../providers/AnalysisTestResultInfo.html'>AnalysisTestResultInfo</a>"
+ + "."),
@Param(
name = "attrs",
allowedTypes = {
@@ -108,9 +111,10 @@
named = true,
defaultValue = "None",
doc =
- "Dictionary declaring the attributes. See the <a href=\"rule.html\">rule</a> call."
- + "Attributes are allowed to use configuration transitions defined using <a "
- + " href=\"#analysis_test_transition\">analysis_test_transition</a>."),
+ "Dictionary declaring the attributes. See the <a"
+ + " href=\"../globals/bzl.html#rule\">rule</a> call. Attributes are allowed to"
+ + " use configuration transitions defined using <a "
+ + " href=\"../globals/bzl.html#analysis_test_transition\">analysis_test_transition</a>."),
@Param(
name = "fragments",
allowedTypes = {@ParamType(type = Sequence.class, generic1 = String.class)},
@@ -125,8 +129,8 @@
named = true,
defaultValue = "[]",
doc =
- "The set of toolchains the test requires. See the <a href=\"#rule\">rule</a>"
- + " call."),
+ "The set of toolchains the test requires. See the <a"
+ + " href=\"../globals/bzl.html#rule\">rule</a> call."),
@Param(
name = "attr_values",
allowedTypes = {@ParamType(type = Dict.class, generic1 = String.class)},
diff --git a/src/main/java/com/google/devtools/build/skydoc/fakebuildapi/FakeStarlarkRuleFunctionsApi.java b/src/main/java/com/google/devtools/build/skydoc/fakebuildapi/FakeStarlarkRuleFunctionsApi.java
index 194fb457..07bf1a9 100644
--- a/src/main/java/com/google/devtools/build/skydoc/fakebuildapi/FakeStarlarkRuleFunctionsApi.java
+++ b/src/main/java/com/google/devtools/build/skydoc/fakebuildapi/FakeStarlarkRuleFunctionsApi.java
@@ -19,7 +19,6 @@
import com.google.devtools.build.lib.cmdline.Label;
import com.google.devtools.build.lib.cmdline.LabelSyntaxException;
import com.google.devtools.build.lib.starlarkbuildapi.ExecGroupApi;
-import com.google.devtools.build.lib.starlarkbuildapi.FileApi;
import com.google.devtools.build.lib.starlarkbuildapi.StarlarkAspectApi;
import com.google.devtools.build.lib.starlarkbuildapi.StarlarkRuleFunctionsApi;
import com.google.devtools.build.skydoc.rendering.AspectInfoWrapper;
@@ -52,9 +51,9 @@
* Fake implementation of {@link StarlarkRuleFunctionsApi}.
*
* <p>This fake hooks into the global {@code rule()} function, adding descriptors of calls of that
- * function to a {@link List} given in the class constructor.</p>
+ * function to a {@link List} given in the class constructor.
*/
-public class FakeStarlarkRuleFunctionsApi implements StarlarkRuleFunctionsApi<FileApi> {
+public class FakeStarlarkRuleFunctionsApi implements StarlarkRuleFunctionsApi {
private static final FakeDescriptor IMPLICIT_NAME_ATTRIBUTE_DESCRIPTOR =
new FakeDescriptor(
diff --git a/src/main/java/net/starlark/java/eval/Dict.java b/src/main/java/net/starlark/java/eval/Dict.java
index ca3fcb7..a9e696a 100644
--- a/src/main/java/net/starlark/java/eval/Dict.java
+++ b/src/main/java/net/starlark/java/eval/Dict.java
@@ -66,8 +66,8 @@
+ " dictionaries are mutable, and may be updated by assigning to <code>d[k]</code> or"
+ " by calling certain methods. Dictionaries are iterable; iteration yields the"
+ " sequence of keys in insertion order. Iteration order is unaffected by updating the"
- + " value associated with an existing key, but is affected by removing then"
- + " reinserting a key.\n"
+ + " value associated with an existing key, but is affected by removing then reinserting"
+ + " a key.\n"
+ "<pre>d = {0: 0, 2: 2, 1: 1}\n"
+ "[k for k in d] # [0, 2, 1]\n"
+ "d.pop(2)\n"
@@ -79,8 +79,7 @@
+ "<ol>\n"
+ "<li>A dictionary expression <code>{k: v, ...}</code> yields a new dictionary with"
+ " the specified key/value entries, inserted in the order they appear in the"
- + " expression. Evaluation fails if any two key expressions yield the same"
- + " value.\n"
+ + " expression. Evaluation fails if any two key expressions yield the same value.\n"
+ "<li>A dictionary comprehension <code>{k: v for vars in seq}</code> yields a new"
+ " dictionary into which each key/value pair is inserted in loop iteration order."
+ " Duplicates are permitted: the first insertion of a given key determines its"
@@ -89,22 +88,20 @@
+ "{k: v for k, v in ((\"a\", 0), (\"b\", 1), (\"a\", 2))} # {\"a\": 2, \"b\": 1}\n"
+ "{i: 2*i for i in range(3)} # {0: 0, 1: 2, 2: 4}\n"
+ "</pre>\n"
- + "<li>A call to the built-in <a href=\"globals.html#dict\">dict</a> function returns"
- + " a dictionary containing the specified entries, which are inserted in argument"
- + " order, positional arguments before named. As with comprehensions, duplicate keys"
- + " are permitted.\n"
+ + "<li>A call to the built-in <a href=\"../globals/all.html#dict\">dict</a> function"
+ + " returns a dictionary containing the specified entries, which are inserted in"
+ + " argument order, positional arguments before named. As with comprehensions,"
+ + " duplicate keys are permitted.\n"
+ "<li>The union expression <code>x | y</code> yields a new dictionary by combining two"
+ " existing dictionaries. If the two dictionaries have a key <code>k</code> in common,"
+ " the right hand side dictionary's value of the key (in other words,"
+ " <code>y[k]</code>) wins. The <code>|=</code> variant of the union operator modifies"
- + " a dictionary in-place. Example:<br>"
- + "<pre class=language-python>"
- + "d = {\"foo\": \"FOO\", \"bar\": \"BAR\"} | {\"foo\": \"FOO2\", \"baz\": \"BAZ\"}\n"
+ + " a dictionary in-place. Example:<br><pre class=language-python>d = {\"foo\":"
+ + " \"FOO\", \"bar\": \"BAR\"} | {\"foo\": \"FOO2\", \"baz\": \"BAZ\"}\n"
+ "# d == {\"foo\": \"FOO2\", \"bar\": \"BAR\", \"baz\": \"BAZ\"}\n"
+ "d = {\"a\": 1, \"b\": 2}\n"
+ "d |= {\"b\": 3, \"c\": 4}\n"
- + "# d == {\"a\": 1, \"b\": 3, \"c\": 4}</pre>"
- + "</ol>")
+ + "# d == {\"a\": 1, \"b\": 3, \"c\": 4}</pre></ol>")
public class Dict<K, V>
implements Map<K, V>,
StarlarkValue,
diff --git a/src/main/java/net/starlark/java/eval/MethodLibrary.java b/src/main/java/net/starlark/java/eval/MethodLibrary.java
index df2467b..955248d 100644
--- a/src/main/java/net/starlark/java/eval/MethodLibrary.java
+++ b/src/main/java/net/starlark/java/eval/MethodLibrary.java
@@ -479,7 +479,7 @@
@StarlarkMethod(
name = "dict",
doc =
- "Creates a <a href=\"dict.html\">dictionary</a> from an optional positional "
+ "Creates a <a href=\"../core/dict.html\">dictionary</a> from an optional positional "
+ "argument and an optional set of keyword arguments. In the case where the same key "
+ "is given multiple times, the last value will be used. Entries supplied via "
+ "keyword arguments are considered to come after entries supplied via the "
diff --git a/src/main/java/net/starlark/java/eval/StringModule.java b/src/main/java/net/starlark/java/eval/StringModule.java
index de84d40..b4cdc13 100644
--- a/src/main/java/net/starlark/java/eval/StringModule.java
+++ b/src/main/java/net/starlark/java/eval/StringModule.java
@@ -962,8 +962,8 @@
+ " to include a brace character in the literal text, it can be escaped by doubling:"
+ " <code>{{</code> and <code>}}</code>A replacement field can be"
+ " either a name, a number, or empty. Values are converted to strings using the <a"
- + " href=\"globals.html#str\">str</a> function.<pre class=\"language-python\">#"
- + " Access in order:\n"
+ + " href=\"../globals/all.html#str\">str</a> function.<pre"
+ + " class=\"language-python\"># Access in order:\n"
+ "\"{} < {}\".format(4, 5) == \"4 < 5\"\n"
+ "# Access by position:\n"
+ "\"{1}, {0}\".format(2, 1) == \"1, 2\"\n"
diff --git a/src/test/java/com/google/devtools/build/docgen/StarlarkDocumentationTest.java b/src/test/java/com/google/devtools/build/docgen/StarlarkDocumentationTest.java
index 877a130..edf2763 100644
--- a/src/test/java/com/google/devtools/build/docgen/StarlarkDocumentationTest.java
+++ b/src/test/java/com/google/devtools/build/docgen/StarlarkDocumentationTest.java
@@ -14,27 +14,29 @@
package com.google.devtools.build.docgen;
import static com.google.common.truth.Truth.assertThat;
-import static com.google.common.truth.Truth.assertWithMessage;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;
+import com.google.common.collect.ImmutableSet;
+import com.google.common.collect.Sets;
+import com.google.devtools.build.docgen.StarlarkDocumentationProcessor.Category;
+import com.google.devtools.build.docgen.annot.DocCategory;
import com.google.devtools.build.docgen.annot.GlobalMethods;
import com.google.devtools.build.docgen.annot.GlobalMethods.Environment;
import com.google.devtools.build.docgen.annot.StarlarkConstructor;
-import com.google.devtools.build.docgen.starlark.StarlarkBuiltinDoc;
import com.google.devtools.build.docgen.starlark.StarlarkConstructorMethodDoc;
+import com.google.devtools.build.docgen.starlark.StarlarkDoc;
import com.google.devtools.build.docgen.starlark.StarlarkDocExpander;
+import com.google.devtools.build.docgen.starlark.StarlarkDocPage;
import com.google.devtools.build.docgen.starlark.StarlarkMethodDoc;
import com.google.devtools.build.lib.analysis.starlark.StarlarkModules;
import com.google.devtools.build.lib.analysis.starlark.StarlarkRuleContext;
import com.google.devtools.build.lib.collect.nestedset.Depset;
-import java.util.ArrayList;
import java.util.Collection;
-import java.util.HashMap;
import java.util.List;
import java.util.Map;
-import java.util.TreeMap;
import java.util.stream.Collectors;
+import java.util.stream.Stream;
import net.starlark.java.annot.Param;
import net.starlark.java.annot.StarlarkBuiltin;
import net.starlark.java.annot.StarlarkMethod;
@@ -72,39 +74,26 @@
private void checkStarlarkTopLevelEnvItemsAreDocumented(Map<String, Object> globals)
throws Exception {
- Map<String, String> docMap = new HashMap<>();
- Map<String, StarlarkBuiltinDoc> modules =
- new TreeMap<>(StarlarkDocumentationCollector.getAllModules(expander));
- StarlarkBuiltinDoc topLevel =
- modules.remove(StarlarkDocumentationCollector.getTopLevelModule().name());
- for (StarlarkMethodDoc method : topLevel.getMethods()) {
- docMap.put(method.getName(), method.getDocumentation());
- }
- for (Map.Entry<String, StarlarkBuiltinDoc> entry : modules.entrySet()) {
- docMap.put(entry.getKey(), entry.getValue().getDocumentation());
- }
+ ImmutableMap<Category, ImmutableList<StarlarkDocPage>> allPages =
+ StarlarkDocumentationCollector.getAllDocPages(expander);
+ ImmutableSet<String> documentedItems =
+ Stream.concat(
+ allPages.get(Category.GLOBAL_FUNCTION).stream()
+ .flatMap(p -> p.getMethods().stream()),
+ allPages.entrySet().stream()
+ .filter(e -> !e.getKey().equals(Category.GLOBAL_FUNCTION))
+ .flatMap(e -> e.getValue().stream()))
+ .filter(m -> !m.getDocumentation().isEmpty())
+ .map(StarlarkDoc::getName)
+ .collect(ImmutableSet.toImmutableSet());
- List<String> undocumentedItems = new ArrayList<>();
- // All built in variables are registered in the Starlark global environment.
- for (String varname : globals.keySet()) {
- if (docMap.containsKey(varname)) {
- if (docMap.get(varname).isEmpty()) {
- undocumentedItems.add(varname);
- }
- } else {
- undocumentedItems.add(varname);
- }
- }
-
- // These constants are currently undocumented.
- // If they need documentation, the easiest approach would be
- // to hard-code it in StarlarkDocumentationCollector.
- undocumentedItems.remove("True");
- undocumentedItems.remove("False");
- undocumentedItems.remove("None");
-
- assertWithMessage("Undocumented items: " + undocumentedItems)
- .that(undocumentedItems)
+ assertThat(
+ Sets.difference(
+ Sets.difference(globals.keySet(), documentedItems),
+ // These constants are currently undocumented.
+ // If they need documentation, the easiest approach would be
+ // to hard-code it in StarlarkDocumentationCollector.
+ ImmutableSet.of("True", "False", "None")))
.containsExactlyElementsIn(DEPRECATED_UNDOCUMENTED_TOP_LEVEL_SYMBOLS);
}
@@ -115,7 +104,7 @@
}
/** MockClassA */
- @StarlarkBuiltin(name = "MockClassA", doc = "MockClassA")
+ @StarlarkBuiltin(name = "MockClassA", category = DocCategory.BUILTIN, doc = "MockClassA")
private static class MockClassA implements StarlarkValue {
@StarlarkMethod(name = "get", doc = "MockClassA#get")
public Integer get() {
@@ -124,7 +113,7 @@
}
/** MockClassD */
- @StarlarkBuiltin(name = "MockClassD", doc = "MockClassD")
+ @StarlarkBuiltin(name = "MockClassD", category = DocCategory.BUILTIN, doc = "MockClassD")
private static class MockClassD implements StarlarkValue {
@StarlarkMethod(
name = "test",
@@ -141,7 +130,7 @@
}
/** MockClassE */
- @StarlarkBuiltin(name = "MockClassE", doc = "MockClassE")
+ @StarlarkBuiltin(name = "MockClassE", category = DocCategory.BUILTIN, doc = "MockClassE")
private static class MockClassE extends MockClassA {
@Override
public Integer get() {
@@ -150,7 +139,7 @@
}
/** MockClassF */
- @StarlarkBuiltin(name = "MockClassF", doc = "MockClassF")
+ @StarlarkBuiltin(name = "MockClassF", category = DocCategory.BUILTIN, doc = "MockClassF")
private static class MockClassF implements StarlarkValue {
@StarlarkMethod(
name = "test",
@@ -168,7 +157,7 @@
}
/** MockClassG */
- @StarlarkBuiltin(name = "MockClassG", doc = "MockClassG")
+ @StarlarkBuiltin(name = "MockClassG", category = DocCategory.BUILTIN, doc = "MockClassG")
private static class MockClassG implements StarlarkValue {
@StarlarkMethod(
name = "test",
@@ -186,7 +175,7 @@
}
/** MockClassH */
- @StarlarkBuiltin(name = "MockClassH", doc = "MockClassH")
+ @StarlarkBuiltin(name = "MockClassH", category = DocCategory.BUILTIN, doc = "MockClassH")
private static class MockClassH implements StarlarkValue {
@StarlarkMethod(
name = "test",
@@ -205,7 +194,7 @@
}
/** MockClassI */
- @StarlarkBuiltin(name = "MockClassI", doc = "MockClassI")
+ @StarlarkBuiltin(name = "MockClassI", category = DocCategory.BUILTIN, doc = "MockClassI")
private static class MockClassI implements StarlarkValue {
@StarlarkMethod(
name = "test",
@@ -255,6 +244,7 @@
/** MockClassWithContainerReturnValues */
@StarlarkBuiltin(
name = "MockClassWithContainerReturnValues",
+ category = DocCategory.BUILTIN,
doc = "MockClassWithContainerReturnValues")
private static class MockClassWithContainerReturnValues implements StarlarkValue {
@@ -285,7 +275,10 @@
}
/** MockClassCommonNameOne */
- @StarlarkBuiltin(name = "MockClassCommonName", doc = "MockClassCommonName")
+ @StarlarkBuiltin(
+ name = "MockClassCommonName",
+ category = DocCategory.BUILTIN,
+ doc = "MockClassCommonName")
private static class MockClassCommonNameOne implements StarlarkValue {
@StarlarkMethod(name = "one", doc = "one")
@@ -295,7 +288,10 @@
}
/** SubclassOfMockClassCommonNameOne */
- @StarlarkBuiltin(name = "MockClassCommonName", doc = "MockClassCommonName")
+ @StarlarkBuiltin(
+ name = "MockClassCommonName",
+ category = DocCategory.BUILTIN,
+ doc = "MockClassCommonName")
private static class SubclassOfMockClassCommonNameOne extends MockClassCommonNameOne {
@StarlarkMethod(name = "two", doc = "two")
@@ -307,6 +303,7 @@
/** PointsToCommonNameOneWithSubclass */
@StarlarkBuiltin(
name = "PointsToCommonNameOneWithSubclass",
+ category = DocCategory.BUILTIN,
doc = "PointsToCommonNameOneWithSubclass")
private static class PointsToCommonNameOneWithSubclass implements StarlarkValue {
@StarlarkMethod(name = "one", doc = "one")
@@ -333,6 +330,7 @@
/** PointsToCommonNameAndUndocumentedModule */
@StarlarkBuiltin(
name = "PointsToCommonNameAndUndocumentedModule",
+ category = DocCategory.BUILTIN,
doc = "PointsToCommonNameAndUndocumentedModule")
private static class PointsToCommonNameAndUndocumentedModule implements StarlarkValue {
@StarlarkMethod(name = "one", doc = "one")
@@ -349,6 +347,7 @@
/** A module which has a selfCall method which constructs copies of MockClassA. */
@StarlarkBuiltin(
name = "MockClassWithSelfCallConstructor",
+ category = DocCategory.BUILTIN,
doc = "MockClassWithSelfCallConstructor")
private static class MockClassWithSelfCallConstructor implements StarlarkValue {
@StarlarkMethod(name = "one", doc = "one")
@@ -365,83 +364,93 @@
@Test
public void testStarlarkCallableParameters() throws Exception {
- Map<String, StarlarkBuiltinDoc> objects = collect(MockClassD.class);
- StarlarkBuiltinDoc moduleDoc = objects.get("MockClassD");
+ ImmutableMap<Category, ImmutableList<StarlarkDocPage>> objects = collect(MockClassD.class);
+ assertThat(objects.get(Category.BUILTIN)).hasSize(1);
+ StarlarkDocPage moduleDoc = objects.get(Category.BUILTIN).get(0);
assertThat(moduleDoc.getDocumentation()).isEqualTo("MockClassD");
assertThat(moduleDoc.getMethods()).hasSize(1);
StarlarkMethodDoc methodDoc = moduleDoc.getMethods().iterator().next();
assertThat(methodDoc.getDocumentation()).isEqualTo("MockClassD#test");
assertThat(methodDoc.getSignature())
.isEqualTo(
- "<a class=\"anchor\" href=\"int.html\">int</a> MockClassD.test(a, b, *, c, d=1)");
+ "<a class=\"anchor\" href=\"../core/int.html\">int</a> MockClassD.test(a, b, *, c,"
+ + " d=1)");
assertThat(methodDoc.getParams()).hasSize(4);
}
@Test
public void testStarlarkCallableParametersAndArgs() throws Exception {
- Map<String, StarlarkBuiltinDoc> objects = collect(MockClassF.class);
- StarlarkBuiltinDoc moduleDoc = objects.get("MockClassF");
+ ImmutableMap<Category, ImmutableList<StarlarkDocPage>> objects = collect(MockClassF.class);
+ assertThat(objects.get(Category.BUILTIN)).hasSize(1);
+ StarlarkDocPage moduleDoc = objects.get(Category.BUILTIN).get(0);
assertThat(moduleDoc.getDocumentation()).isEqualTo("MockClassF");
assertThat(moduleDoc.getMethods()).hasSize(1);
StarlarkMethodDoc methodDoc = moduleDoc.getMethods().iterator().next();
assertThat(methodDoc.getDocumentation()).isEqualTo("MockClassF#test");
assertThat(methodDoc.getSignature())
.isEqualTo(
- "<a class=\"anchor\" href=\"int.html\">int</a> "
+ "<a class=\"anchor\" href=\"../core/int.html\">int</a> "
+ "MockClassF.test(a, b, *, c, d=1, *myArgs)");
assertThat(methodDoc.getParams()).hasSize(5);
}
@Test
public void testStarlarkCallableParametersAndKwargs() throws Exception {
- Map<String, StarlarkBuiltinDoc> objects = collect(MockClassG.class);
- StarlarkBuiltinDoc moduleDoc = objects.get("MockClassG");
+ ImmutableMap<Category, ImmutableList<StarlarkDocPage>> objects = collect(MockClassG.class);
+ assertThat(objects.get(Category.BUILTIN)).hasSize(1);
+ StarlarkDocPage moduleDoc = objects.get(Category.BUILTIN).get(0);
assertThat(moduleDoc.getDocumentation()).isEqualTo("MockClassG");
assertThat(moduleDoc.getMethods()).hasSize(1);
StarlarkMethodDoc methodDoc = moduleDoc.getMethods().iterator().next();
assertThat(methodDoc.getDocumentation()).isEqualTo("MockClassG#test");
assertThat(methodDoc.getSignature())
.isEqualTo(
- "<a class=\"anchor\" href=\"int.html\">int</a> "
+ "<a class=\"anchor\" href=\"../core/int.html\">int</a> "
+ "MockClassG.test(a, b, *, c, d=1, **myKwargs)");
assertThat(methodDoc.getParams()).hasSize(5);
}
@Test
public void testStarlarkCallableParametersAndArgsAndKwargs() throws Exception {
- Map<String, StarlarkBuiltinDoc> objects = collect(MockClassH.class);
- StarlarkBuiltinDoc moduleDoc = objects.get("MockClassH");
+ ImmutableMap<Category, ImmutableList<StarlarkDocPage>> objects = collect(MockClassH.class);
+ assertThat(objects.get(Category.BUILTIN)).hasSize(1);
+ StarlarkDocPage moduleDoc = objects.get(Category.BUILTIN).get(0);
assertThat(moduleDoc.getDocumentation()).isEqualTo("MockClassH");
assertThat(moduleDoc.getMethods()).hasSize(1);
StarlarkMethodDoc methodDoc = moduleDoc.getMethods().iterator().next();
assertThat(methodDoc.getDocumentation()).isEqualTo("MockClassH#test");
assertThat(methodDoc.getSignature())
.isEqualTo(
- "<a class=\"anchor\" href=\"int.html\">int</a> "
+ "<a class=\"anchor\" href=\"../core/int.html\">int</a> "
+ "MockClassH.test(a, b, *, c, d=1, *myArgs, **myKwargs)");
assertThat(methodDoc.getParams()).hasSize(6);
}
@Test
public void testStarlarkUndocumentedParameters() throws Exception {
- Map<String, StarlarkBuiltinDoc> objects = collect(MockClassI.class);
- StarlarkBuiltinDoc moduleDoc = objects.get("MockClassI");
+ ImmutableMap<Category, ImmutableList<StarlarkDocPage>> objects = collect(MockClassI.class);
+ assertThat(objects.get(Category.BUILTIN)).hasSize(1);
+ StarlarkDocPage moduleDoc = objects.get(Category.BUILTIN).get(0);
assertThat(moduleDoc.getDocumentation()).isEqualTo("MockClassI");
assertThat(moduleDoc.getMethods()).hasSize(1);
StarlarkMethodDoc methodDoc = moduleDoc.getMethods().iterator().next();
assertThat(methodDoc.getDocumentation()).isEqualTo("MockClassI#test");
assertThat(methodDoc.getSignature())
.isEqualTo(
- "<a class=\"anchor\" href=\"int.html\">int</a> "
+ "<a class=\"anchor\" href=\"../core/int.html\">int</a> "
+ "MockClassI.test(a, b, *, c, d=1, *myArgs)");
assertThat(methodDoc.getParams()).hasSize(5);
}
@Test
public void testStarlarkGlobalLibraryCallable() throws Exception {
- StarlarkBuiltinDoc topLevel =
- StarlarkDocumentationCollector.getAllModules(expander)
- .get(StarlarkDocumentationCollector.getTopLevelModule().name());
+ StarlarkDocPage topLevel =
+ StarlarkDocumentationCollector.getAllDocPages(expander)
+ .get(Category.GLOBAL_FUNCTION)
+ .stream()
+ .filter(p -> p.getTitle().equals(Environment.BZL.getTitle()))
+ .findAny()
+ .get();
boolean foundGlobalLibrary = false;
for (StarlarkMethodDoc methodDoc : topLevel.getMethods()) {
@@ -449,7 +458,7 @@
assertThat(methodDoc.getDocumentation()).isEqualTo("GlobalCallable documentation");
assertThat(methodDoc.getSignature())
.isEqualTo(
- "<a class=\"anchor\" href=\"int.html\">int</a> "
+ "<a class=\"anchor\" href=\"../core/int.html\">int</a> "
+ "MockGlobalCallable(a, b, *, c, d=1, *myArgs, **myKwargs)");
foundGlobalLibrary = true;
break;
@@ -460,84 +469,98 @@
@Test
public void testStarlarkCallableOverriding() throws Exception {
- Map<String, StarlarkBuiltinDoc> objects =
- collect(ImmutableList.of(MockClassA.class, MockClassE.class));
- StarlarkBuiltinDoc moduleDoc = objects.get("MockClassE");
+ ImmutableMap<Category, ImmutableList<StarlarkDocPage>> objects =
+ collect(MockClassA.class, MockClassE.class);
+ StarlarkDocPage moduleDoc =
+ objects.get(Category.BUILTIN).stream()
+ .filter(p -> p.getTitle().equals("MockClassE"))
+ .findAny()
+ .get();
assertThat(moduleDoc.getDocumentation()).isEqualTo("MockClassE");
assertThat(moduleDoc.getMethods()).hasSize(1);
StarlarkMethodDoc methodDoc = moduleDoc.getMethods().iterator().next();
assertThat(methodDoc.getDocumentation()).isEqualTo("MockClassA#get");
assertThat(methodDoc.getSignature())
- .isEqualTo("<a class=\"anchor\" href=\"int.html\">int</a> MockClassE.get()");
+ .isEqualTo("<a class=\"anchor\" href=\"../core/int.html\">int</a> MockClassE.get()");
}
@Test
public void testStarlarkContainerReturnTypesWithoutAnnotations() throws Exception {
- Map<String, StarlarkBuiltinDoc> objects = collect(MockClassWithContainerReturnValues.class);
- assertThat(objects).containsKey("MockClassWithContainerReturnValues");
- Collection<? extends StarlarkMethodDoc> methods =
- objects.get("MockClassWithContainerReturnValues").getMethods();
+ ImmutableMap<Category, ImmutableList<StarlarkDocPage>> objects =
+ collect(MockClassWithContainerReturnValues.class);
+ assertThat(objects.get(Category.BUILTIN)).hasSize(1);
+ StarlarkDocPage moduleDoc = objects.get(Category.BUILTIN).get(0);
+ Collection<? extends StarlarkMethodDoc> methods = moduleDoc.getMethods();
List<String> signatures =
methods.stream().map(m -> m.getSignature()).collect(Collectors.toList());
assertThat(signatures).hasSize(5);
assertThat(signatures)
.contains(
- "<a class=\"anchor\" href=\"depset.html\">depset</a> "
+ "<a class=\"anchor\" href=\"../builtins/depset.html\">depset</a> "
+ "MockClassWithContainerReturnValues.depset()");
assertThat(signatures)
.contains(
- "<a class=\"anchor\" href=\"tuple.html\">tuple</a> "
+ "<a class=\"anchor\" href=\"../core/tuple.html\">tuple</a> "
+ "MockClassWithContainerReturnValues.tuple()");
assertThat(signatures)
.contains(
- "<a class=\"anchor\" href=\"list.html\">list</a> "
+ "<a class=\"anchor\" href=\"../core/list.html\">list</a> "
+ "MockClassWithContainerReturnValues.immutable()");
assertThat(signatures)
.contains(
- "<a class=\"anchor\" href=\"list.html\">list</a> "
+ "<a class=\"anchor\" href=\"../core/list.html\">list</a> "
+ "MockClassWithContainerReturnValues.mutable()");
assertThat(signatures)
.contains(
- "<a class=\"anchor\" href=\"list.html\">sequence</a> "
+ "<a class=\"anchor\" href=\"../core/list.html\">sequence</a> "
+ "MockClassWithContainerReturnValues.starlark()");
}
@Test
public void testDocumentedModuleTakesPrecedence() throws Exception {
- Map<String, StarlarkBuiltinDoc> objects =
+ ImmutableMap<Category, ImmutableList<StarlarkDocPage>> objects =
collect(
- ImmutableList.of(
- PointsToCommonNameAndUndocumentedModule.class,
- MockClassCommonNameOne.class,
- MockClassCommonNameUndocumented.class));
+ PointsToCommonNameAndUndocumentedModule.class,
+ MockClassCommonNameOne.class,
+ MockClassCommonNameUndocumented.class);
Collection<? extends StarlarkMethodDoc> methods =
- objects.get("MockClassCommonName").getMethods();
- List<String> methodNames =
- methods.stream().map(m -> m.getName()).collect(Collectors.toList());
+ objects.get(Category.BUILTIN).stream()
+ .filter(p -> p.getTitle().equals("MockClassCommonName"))
+ .findAny()
+ .get()
+ .getMethods();
+ List<String> methodNames = methods.stream().map(m -> m.getName()).collect(Collectors.toList());
assertThat(methodNames).containsExactly("one");
}
@Test
public void testDocumentModuleSubclass() {
- Map<String, StarlarkBuiltinDoc> objects =
+ ImmutableMap<Category, ImmutableList<StarlarkDocPage>> objects =
collect(
- ImmutableList.of(
- PointsToCommonNameOneWithSubclass.class,
- MockClassCommonNameOne.class,
- SubclassOfMockClassCommonNameOne.class));
+ PointsToCommonNameOneWithSubclass.class,
+ MockClassCommonNameOne.class,
+ SubclassOfMockClassCommonNameOne.class);
Collection<? extends StarlarkMethodDoc> methods =
- objects.get("MockClassCommonName").getMethods();
- List<String> methodNames =
- methods.stream().map(m -> m.getName()).collect(Collectors.toList());
+ objects.get(Category.BUILTIN).stream()
+ .filter(p -> p.getTitle().equals("MockClassCommonName"))
+ .findAny()
+ .get()
+ .getMethods();
+ List<String> methodNames = methods.stream().map(m -> m.getName()).collect(Collectors.toList());
assertThat(methodNames).containsExactly("one", "two");
}
@Test
public void testDocumentSelfcallConstructor() {
- Map<String, StarlarkBuiltinDoc> objects =
- collect(ImmutableList.of(MockClassA.class, MockClassWithSelfCallConstructor.class));
- Collection<? extends StarlarkMethodDoc> methods = objects.get("MockClassA").getMethods();
+ ImmutableMap<Category, ImmutableList<StarlarkDocPage>> objects =
+ collect(MockClassA.class, MockClassWithSelfCallConstructor.class);
+ Collection<? extends StarlarkMethodDoc> methods =
+ objects.get(Category.BUILTIN).stream()
+ .filter(p -> p.getTitle().equals("MockClassA"))
+ .findAny()
+ .get()
+ .getMethods();
StarlarkMethodDoc firstMethod = methods.iterator().next();
assertThat(firstMethod).isInstanceOf(StarlarkConstructorMethodDoc.class);
@@ -545,11 +568,8 @@
assertThat(methodNames).containsExactly("MockClassA", "get");
}
- private Map<String, StarlarkBuiltinDoc> collect(Iterable<Class<?>> classObjects) {
- return StarlarkDocumentationCollector.collectModules(classObjects, expander);
- }
-
- private Map<String, StarlarkBuiltinDoc> collect(Class<?> classObject) {
- return collect(ImmutableList.of(classObject));
+ private ImmutableMap<Category, ImmutableList<StarlarkDocPage>> collect(Class<?>... classObjects) {
+ return StarlarkDocumentationCollector.collectDocPages(
+ ImmutableList.copyOf(classObjects), expander);
}
}
