diff options
author | Alexandre Rostovtsev <arostovtsev@google.com> | 2022-09-01 08:19:43 -0400 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-09-01 08:19:43 -0400 |
commit | d7e9dbb31fb41f2d4c5073cf2800e6f99e83d545 (patch) | |
tree | 605cfc1706bd5fc5efea7a3c03dee89b6578a2f8 | |
parent | 31ab4c8bd2386238ed204e8cd3c271c6eef601ef (diff) | |
download | bazel-skylib-d7e9dbb31fb41f2d4c5073cf2800e6f99e83d545.tar.gz |
Add missing docs and doc links; update bazel.build links (#387)
-rw-r--r-- | README.md | 6 | ||||
-rw-r--r-- | docs/BUILD | 5 | ||||
-rwxr-xr-x | docs/build_test_doc.md | 2 | ||||
-rwxr-xr-x | docs/common_settings_doc.md | 2 | ||||
-rwxr-xr-x | docs/diff_test_doc.md | 2 | ||||
-rwxr-xr-x | docs/native_binary_doc.md | 4 | ||||
-rwxr-xr-x | docs/run_binary_doc.md | 4 | ||||
-rwxr-xr-x | docs/select_file_doc.md | 28 | ||||
-rw-r--r-- | rules/build_test.bzl | 2 | ||||
-rw-r--r-- | rules/common_settings.bzl | 2 | ||||
-rw-r--r-- | rules/diff_test.bzl | 2 | ||||
-rw-r--r-- | rules/native_binary.bzl | 2 | ||||
-rw-r--r-- | rules/run_binary.bzl | 4 | ||||
-rw-r--r-- | rules/select_file.bzl | 5 |
14 files changed, 54 insertions, 16 deletions
@@ -60,8 +60,14 @@ s = shell.quote(p) * [analysis_test](docs/analysis_test_doc.md) * [build_test](docs/build_test_doc.md) +* [common_settings](docs/common_settings_doc.md) +* [copy_directory](docs/copy_directory_doc.md) * [copy_file](docs/copy_file_doc.md) +* [diff_test](docs/diff_test_doc.md) * [expand_template](docs/expand_template_doc.md) +* [native_binary and native_test](docs/native_binary_doc.md) +* [run_binary](docs/run_binary_doc.md) +* [select_file](docs/select_file_doc.md) * [write_file](docs/write_file_doc.md) ## Writing a new module @@ -78,6 +78,11 @@ stardoc_with_diff_test( ) stardoc_with_diff_test( + bzl_library_target = "//rules:select_file", + out_label = "//docs:select_file_doc.md", +) + +stardoc_with_diff_test( bzl_library_target = "//lib:shell", out_label = "//docs:shell_doc.md", ) diff --git a/docs/build_test_doc.md b/docs/build_test_doc.md index eba4904..d547406 100755 --- a/docs/build_test_doc.md +++ b/docs/build_test_doc.md @@ -36,6 +36,6 @@ Typical usage: | :------------- | :------------- | :------------- | | <a id="build_test-name"></a>name | The name of the test rule. | none | | <a id="build_test-targets"></a>targets | A list of targets to ensure build. | none | -| <a id="build_test-kwargs"></a>kwargs | The <a href="https://docs.bazel.build/versions/main/be/common-definitions.html#common-attributes-tests">common attributes for tests</a>. | none | +| <a id="build_test-kwargs"></a>kwargs | The <a href="https://bazel.build/reference/be/common-definitions#common-attributes-tests">common attributes for tests</a>. | none | diff --git a/docs/common_settings_doc.md b/docs/common_settings_doc.md index 5ab7cd2..4dda47c 100755 --- a/docs/common_settings_doc.md +++ b/docs/common_settings_doc.md @@ -6,7 +6,7 @@ These rules return a BuildSettingInfo with the value of the build setting. For label-typed settings, use the native label_flag and label_setting rules. More documentation on how to use build settings at -https://docs.bazel.build/versions/main/skylark/config.html#user-defined-build-settings +https://bazel.build/extending/config#user-defined-build-settings <a id="bool_flag"></a> diff --git a/docs/diff_test_doc.md b/docs/diff_test_doc.md index 41a030b..4fc2416 100755 --- a/docs/diff_test_doc.md +++ b/docs/diff_test_doc.md @@ -28,6 +28,6 @@ The test succeeds if the files' contents match. | <a id="diff_test-file1"></a>file1 | Label of the file to compare to <code>file2</code>. | none | | <a id="diff_test-file2"></a>file2 | Label of the file to compare to <code>file1</code>. | none | | <a id="diff_test-failure_message"></a>failure_message | Additional message to log if the files' contents do not match. | <code>None</code> | -| <a id="diff_test-kwargs"></a>kwargs | The <a href="https://docs.bazel.build/versions/main/be/common-definitions.html#common-attributes-tests">common attributes for tests</a>. | none | +| <a id="diff_test-kwargs"></a>kwargs | The <a href="https://bazel.build/reference/be/common-definitions#common-attributes-tests">common attributes for tests</a>. | none | diff --git a/docs/native_binary_doc.md b/docs/native_binary_doc.md index 7a54315..b512b25 100755 --- a/docs/native_binary_doc.md +++ b/docs/native_binary_doc.md @@ -29,7 +29,7 @@ in genrule.tools for example. You can also augment the binary with runfiles. | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | <a id="native_binary-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | | -| <a id="native_binary-data"></a>data | data dependencies. See https://docs.bazel.build/versions/main/be/common-definitions.html#typical.data | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] | +| <a id="native_binary-data"></a>data | data dependencies. See https://bazel.build/reference/be/common-definitions#typical.data | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] | | <a id="native_binary-out"></a>out | An output name for the copy of the binary | String | required | | | <a id="native_binary-src"></a>src | path of the pre-built executable | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required | | @@ -55,7 +55,7 @@ the binary with runfiles. | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | <a id="native_test-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | | -| <a id="native_test-data"></a>data | data dependencies. See https://docs.bazel.build/versions/main/be/common-definitions.html#typical.data | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] | +| <a id="native_test-data"></a>data | data dependencies. See https://bazel.build/reference/be/common-definitions#typical.data | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] | | <a id="native_test-out"></a>out | An output name for the copy of the binary | String | required | | | <a id="native_test-src"></a>src | path of the pre-built executable | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required | | diff --git a/docs/run_binary_doc.md b/docs/run_binary_doc.md index 7d4f9fb..8e4491d 100755 --- a/docs/run_binary_doc.md +++ b/docs/run_binary_doc.md @@ -22,8 +22,8 @@ Runs a binary as a build action.<br/><br/>This rule does not require Bash (unlik | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | <a id="run_binary-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | | -| <a id="run_binary-args"></a>args | Command line arguments of the binary.<br/><br/>Subject to<code><a href="https://docs.bazel.build/versions/main/be/make-variables.html#location">$(location)</a></code> expansion. | List of strings | optional | [] | -| <a id="run_binary-env"></a>env | Environment variables of the action.<br/><br/>Subject to <code><a href="https://docs.bazel.build/versions/main/be/make-variables.html#location">$(location)</a></code> expansion. | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | optional | {} | +| <a id="run_binary-args"></a>args | Command line arguments of the binary.<br/><br/>Subject to<code><a href="https://bazel.build/reference/be/make-variables#predefined_label_variables">$(location)</a></code> expansion. | List of strings | optional | [] | +| <a id="run_binary-env"></a>env | Environment variables of the action.<br/><br/>Subject to <code><a href="https://bazel.build/reference/be/make-variables#predefined_label_variables">$(location)</a></code> expansion. | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | optional | {} | | <a id="run_binary-outs"></a>outs | Output files generated by the action.<br/><br/>These labels are available for <code>$(location)</code> expansion in <code>args</code> and <code>env</code>. | List of labels | required | | | <a id="run_binary-srcs"></a>srcs | Additional inputs of the action.<br/><br/>These labels are available for <code>$(location)</code> expansion in <code>args</code> and <code>env</code>. | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] | | <a id="run_binary-tool"></a>tool | The tool to run in the action.<br/><br/>Must be the label of a *_binary rule, of a rule that generates an executable file, or of a file that can be executed as a subprocess (e.g. an .exe or .bat file on Windows or a binary with executable permission on Linux). This label is available for <code>$(location)</code> expansion in <code>args</code> and <code>env</code>. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required | | diff --git a/docs/select_file_doc.md b/docs/select_file_doc.md new file mode 100755 index 0000000..667f519 --- /dev/null +++ b/docs/select_file_doc.md @@ -0,0 +1,28 @@ +<!-- Generated with Stardoc: http://skydoc.bazel.build --> + + +select_file() build rule implementation. + +Selects a single file from the outputs of a target by given relative path. + + +<a id="select_file"></a> + +## select_file + +<pre> +select_file(<a href="#select_file-name">name</a>, <a href="#select_file-srcs">srcs</a>, <a href="#select_file-subpath">subpath</a>) +</pre> + +Selects a single file from the outputs of a target by given relative path + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| <a id="select_file-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | | +| <a id="select_file-srcs"></a>srcs | The target producing the file among other outputs | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required | | +| <a id="select_file-subpath"></a>subpath | Relative path to the file | String | required | | + + diff --git a/rules/build_test.bzl b/rules/build_test.bzl index 9ec8ab1..682901e 100644 --- a/rules/build_test.bzl +++ b/rules/build_test.bzl @@ -63,7 +63,7 @@ def build_test(name, targets, **kwargs): Args: name: The name of the test rule. targets: A list of targets to ensure build. - **kwargs: The <a href="https://docs.bazel.build/versions/main/be/common-definitions.html#common-attributes-tests">common attributes for tests</a>. + **kwargs: The <a href="https://bazel.build/reference/be/common-definitions#common-attributes-tests">common attributes for tests</a>. """ if len(targets) == 0: fail("targets must be non-empty", "targets") diff --git a/rules/common_settings.bzl b/rules/common_settings.bzl index 7f56a7f..d5b8408 100644 --- a/rules/common_settings.bzl +++ b/rules/common_settings.bzl @@ -18,7 +18,7 @@ These rules return a BuildSettingInfo with the value of the build setting. For label-typed settings, use the native label_flag and label_setting rules. More documentation on how to use build settings at -https://docs.bazel.build/versions/main/skylark/config.html#user-defined-build-settings +https://bazel.build/extending/config#user-defined-build-settings """ BuildSettingInfo = provider( diff --git a/rules/diff_test.bzl b/rules/diff_test.bzl index 25213d6..ee2f589 100644 --- a/rules/diff_test.bzl +++ b/rules/diff_test.bzl @@ -164,7 +164,7 @@ def diff_test(name, file1, file2, failure_message = None, **kwargs): file1: Label of the file to compare to <code>file2</code>. file2: Label of the file to compare to <code>file1</code>. failure_message: Additional message to log if the files' contents do not match. - **kwargs: The <a href="https://docs.bazel.build/versions/main/be/common-definitions.html#common-attributes-tests">common attributes for tests</a>. + **kwargs: The <a href="https://bazel.build/reference/be/common-definitions#common-attributes-tests">common attributes for tests</a>. """ _diff_test( name = name, diff --git a/rules/native_binary.bzl b/rules/native_binary.bzl index a027fc9..b33347b 100644 --- a/rules/native_binary.bzl +++ b/rules/native_binary.bzl @@ -61,7 +61,7 @@ _ATTRS = { "data": attr.label_list( allow_files = True, doc = "data dependencies. See" + - " https://docs.bazel.build/versions/main/be/common-definitions.html#typical.data", + " https://bazel.build/reference/be/common-definitions#typical.data", ), # "out" is attr.string instead of attr.output, so that it is select()'able. "out": attr.string(mandatory = True, doc = "An output name for the copy of the binary"), diff --git a/rules/run_binary.bzl b/rules/run_binary.bzl index 47c8bc5..c40c0be 100644 --- a/rules/run_binary.bzl +++ b/rules/run_binary.bzl @@ -76,7 +76,7 @@ run_binary = rule( ), "env": attr.string_dict( doc = "Environment variables of the action.<br/><br/>Subject to " + - " <code><a href=\"https://docs.bazel.build/versions/main/be/make-variables.html#location\">$(location)</a></code>" + + " <code><a href=\"https://bazel.build/reference/be/make-variables#predefined_label_variables\">$(location)</a></code>" + " expansion.", ), "srcs": attr.label_list( @@ -91,7 +91,7 @@ run_binary = rule( ), "args": attr.string_list( doc = "Command line arguments of the binary.<br/><br/>Subject to" + - "<code><a href=\"https://docs.bazel.build/versions/main/be/make-variables.html#location\">$(location)</a></code>" + + "<code><a href=\"https://bazel.build/reference/be/make-variables#predefined_label_variables\">$(location)</a></code>" + " expansion.", ), }, diff --git a/rules/select_file.bzl b/rules/select_file.bzl index f359e43..1b73093 100644 --- a/rules/select_file.bzl +++ b/rules/select_file.bzl @@ -15,7 +15,7 @@ """ select_file() build rule implementation. -Selects a single file from the outputs of some target by given relative path. +Selects a single file from the outputs of a target by given relative path. """ def _impl(ctx): @@ -38,8 +38,7 @@ def _impl(ctx): select_file = rule( implementation = _impl, - doc = "Selects a single file from the outputs of some target \ -by given relative path", + doc = "Selects a single file from the outputs of a target by given relative path", attrs = { "srcs": attr.label( allow_files = True, |