Clean up attribute documentation hoping to make it clearer. Specifically that labels and label_lists are actually of type Target, and adding more cross linking to various documentation to make it easier to peruse.

Tested all of the links to make sure they work.

--
MOS_MIGRATED_REVID=116076080

1 files changed, 37 insertions, 38 deletions

diff --git a/site/docs/skylark/rules.md b/site/docs/skylark/rules.md
index 552df3072a..8123a0a7e1 100644
--- a/site/docs/skylark/rules.md
+++ b/site/docs/skylark/rules.md
@@ -2,14 +2,12 @@
 layout: documentation
 title: Skylark Rules
 ---
-Rules
-=====
+# Rules
 
 **Status: Experimental**. We may make breaking changes to the API, but we will
   help you update your code.
 
-Rule creation
--------------
+## Rule creation
 
 In a Skylark extension, use the [rule](lib/globals.html#rule) function
 to create a new rule and store it in a global variable.
@@ -25,8 +23,7 @@ function decides what the outputs of the rule are and how to build them (using
 `actions`). During analysis, no external command can be executed: actions will
 be run in the execution phase.
 
-Attributes
-----------
+## Attributes
 
 An attribute is a rule argument, such as `srcs` or `deps`. You must list
 the attributes and their types when you define a rule.
@@ -41,10 +38,6 @@ sum = rule(
 )
 ```
 
-If an attribute starts with `_`, it is private and users cannot set it. It
-is useful in particular for label attributes (your rule will have an
-implicit dependency on this label).
-
 The following attributes are implicitly added to every rule: `deprecation`,
 `features`, `name`, `tags`, `testonly`, `visibility`. Test rules also have the
 following attributes: `args`, `flaky`, `local`, `shard_count`, `size`, `timeout`.
@@ -54,8 +47,27 @@ package of a rule are available with `ctx.label.name` and `ctx.label.package`.
 
 [See example.](cookbook.md#attr)
 
-Implementation function
------------------------
+### <a name="private-attributes"></a> Private Attributes
+
+If an attribute name starts with `_` it is private and users cannot set it. It
+is useful in particular for label attributes (your rule will have an
+implicit dependency on this label).
+
+```python
+metal_compile = rule(
+    implementation=impl,
+    attrs={
+        "srcs": attr.label_list(),
+        "_compiler": attr.label(
+            default=Label("//tools:metalc"),
+            single_file=True,
+            executable=True,
+        ),
+    },
+)
+```
+
+## Implementation function
 
 Every rule requires an `implementation` function. It contains the actual
 logic of the rule and is executed strictly in the Analysis Phase. The function
@@ -80,16 +92,14 @@ my_rule = rule(
 )
 ```
 
-Files
------
+## Files
 
 There are two kinds of files: files stored in the file system and generated
 files. For each generated file, there must be one and only one generating
 action, and each action must generate one or more output files. Bazel will throw
 an error otherwise.
 
-Targets
--------
+## Targets
 
 Every build rule corresponds to exactly one target. A target can create
 [actions](#actions), can have dependencies (which can be files or
@@ -127,9 +137,7 @@ my_rule = rule(
 )
 ```
 
-<a name="output-files"></a>
-Output files
-------------
+## <a name="output-files"></a> Output files
 
 A target can declare output files, which must be generated by the target's
 actions. There are three ways to create output files in Skylark:
@@ -147,8 +155,7 @@ actions. There are three ways to create output files in Skylark:
 All output files must have exactly one generating action. See the
 [library](lib/ctx.html#outputs) for more context.
 
-Default outputs
----------------
+## Default outputs
 
 Every rule has a set of default outputs. This is used:
 
@@ -174,8 +181,7 @@ This can be useful for exposing files generated with
 outputs", i.e., files that are declared in the rule, but not in the default
 outputs (like `_deploy.jar` in `java_binary`).
 
-Actions
--------
+## Actions
 
 There are three ways to create actions:
 
@@ -219,8 +225,7 @@ executed. It is an error if there is a cycle in the dependency graph. Creating
 an action does not guarantee that it will be executed: It depends on whether
 its outputs are needed for the build.
 
-Configurations
---------------
+## Configurations
 
 By default, a target is built in the target configuration. For each label
 attribute, you can decide whether the dependency should be built in the same
@@ -236,9 +241,8 @@ in the attribute.
 `DATA_CFG` is present for legacy reasons and should be used for `data`
 attributes.
 
-<a name="fragments"></a>
-Configuration Fragments
---------------
+
+## <a name="fragments"></a> Configuration Fragments
 
 Rules may access configuration fragments such as `cpp`, `java` and `jvm`.
 However, all required fragments must be declared in order to avoid access
@@ -262,8 +266,7 @@ my_rule = rule(
 configuration. If you want to access fragments for the host configuration,
 use `ctx.host_fragments` instead.
 
-Providers
----------
+## Providers
 
 Providers are used to access information from other rules. A rule depending on
 another rule has access to the data the latter provides. These data can be e.g.
@@ -316,8 +319,7 @@ Providers are only available during the analysis phase. Examples of usage:
 * [mandatory providers](cookbook.md#mandatory-providers)
 * [optional providers](cookbook.md#optional-providers)
 
-Runfiles
---------
+## Runfiles
 
 Runfiles are a set of files used by the (often executable) output of a rule
 during runtime (as opposed to build time, i.e. when the binary itself is
@@ -357,8 +359,7 @@ binary should know about them.
 Also note that if an action uses an executable, the executable's runfiles can
 be used when the action executes.
 
-Instrumented files
-------------------
+## Instrumented files
 
 Instrumented files are a set of files used by the coverage command. A rule can
 use the `instrumented_files` provider to provide information about which files
@@ -380,8 +381,7 @@ def rule_implementation(ctx):
       dependency_attributes=["data", "deps"]))
 ```
 
-Executable rules
-----------------
+## Executable rules
 
 An executable rule is a rule that users can run using `bazel run`.
 
@@ -390,8 +390,7 @@ To make a rule executable, set `executable=True` in the
 phase, the rule must generate the output file `ctx.outputs.executable`.
 [See example](cookbook.md#outputs-executable)
 
-Test rules
-----------
+## Test rules
 
 Test rules are run using `bazel test`.