Docs: Code updates for Bazel macro file
PiperOrigin-RevId: 380068467
diff --git a/site/docs/skylark/macros.md b/site/docs/skylark/macros.md
index 6e0cd8c..e879106 100644
--- a/site/docs/skylark/macros.md
+++ b/site/docs/skylark/macros.md
@@ -10,7 +10,7 @@
This page covers the basics of using macros and includes typical use cases,
debugging, and conventions.
-A macro is a function called from the BUILD file that can instantiate rules.
+A macro is a function called from the `BUILD` file that can instantiate rules.
Macros are mainly used for encapsulation and code reuse of existing rules
and other macros. By the end of the
[loading phase](concepts.md#evaluation-model), macros don't exist anymore,
@@ -20,7 +20,7 @@
The typical use case for a macro is when you want to reuse a rule.
-For example, genrule in a BUILD file generates a file using
+For example, genrule in a `BUILD` file generates a file using
`//:generator` with a `some_arg` argument hardcoded in the command:
```python
@@ -61,7 +61,7 @@
Here, you load the `file_generator` symbol from a `.bzl` file located
in the `//path` package. By putting macro function definitions in a separate
-`.bzl` file, you keep your BUILD files clean and declarative, The `.bzl`
+`.bzl` file, you keep your `BUILD` files clean and declarative, The `.bzl`
file can be loaded from any package in the workspace.
Finally, in `path/generator.bzl`, write the definition of the macro to
@@ -138,14 +138,14 @@
)
```
-If you need to know the package name (i.e. which BUILD file is calling the
+If you need to know the package name (i.e. which `BUILD` file is calling the
macro), use the function [native.package_name()](lib/native.html#package_name).
-Note that `native` can only be used in `.bzl` files, and not in WORKSPACE or
-BUILD.
+Note that `native` can only be used in `.bzl` files, and not in `WORKSPACE` or
+`BUILD` files.
## Debugging
-* `bazel query --output=build //my/path:all` will show you how the BUILD file
+* `bazel query --output=build //my/path:all` will show you how the `BUILD` file
looks after evaluation. All macros, globs, loops are expanded. Known
limitation: `select` expressions are currently not shown in the output.
@@ -156,8 +156,8 @@
$ bazel query --output=build 'attr(generator_function, my_macro, //my/path:all)'
```
-* To find out where exactly the rule `foo` is generated in a BUILD file, you
- can try the following trick. Insert this line near the top of the BUILD
+* To find out where exactly the rule `foo` is generated in a `BUILD` file, you
+ can try the following trick. Insert this line near the top of the `BUILD`
file: `cc_library(name = "foo")`. Run Bazel. You will get an exception when
the rule `foo` is created (due to a name conflict), which will show you the
full stack trace.
@@ -171,8 +171,8 @@
## Errors
If you want to throw an error, use the [fail](lib/globals.html#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.
+Explain clearly to the user what went wrong and how to fix their `BUILD` file.
+It is not possible to catch an error.
```python
def my_macro(name, deps, visibility=None):
@@ -190,8 +190,8 @@
* Public functions should use a docstring following [Python
conventions](https://www.python.org/dev/peps/pep-0257/#one-line-docstrings).
-* In BUILD files, the `name` argument of the macros must be a keyword argument
- (not a positional argument).
+* In `BUILD` files, the `name` argument of the macros must be a keyword
+ argument (not a positional argument).
* The `name` attribute of rules generated by a macro should include the name
argument as a prefix. For example, `macro(name = "foo")` can generate a
