Docs: Update code fonts for Starlark files
PiperOrigin-RevId: 377601312
diff --git a/site/docs/skylark/aspects.md b/site/docs/skylark/aspects.md
index 1dbf4f0..ab539d5 100644
--- a/site/docs/skylark/aspects.md
+++ b/site/docs/skylark/aspects.md
@@ -15,14 +15,14 @@
* IDEs that integrate Bazel can use aspects to collect information about the
project.
* Code generation tools can leverage aspects to execute on their inputs in
- "target-agnostic" manner. As an example, BUILD files can specify a hierarchy
+ *target-agnostic* manner. As an example, `BUILD` files can specify a hierarchy
of [protobuf](https://developers.google.com/protocol-buffers/) library
definitions, and language-specific rules can use aspects to attach
actions generating protobuf support code for a particular language.
## Aspect basics
-Bazel BUILD files provide a description of a project’s source code: what source
+Bazel `BUILD` files provide a description of a project’s source code: what source
files are part of the project, what artifacts (_targets_) should be built from
those files, what the dependencies between those files are, etc. Bazel uses
this information to perform a build, that is, it figures out the set of actions
@@ -30,7 +30,7 @@
executes those actions. Bazel accomplishes this by constructing a _dependency
graph_ between targets and visiting this graph to collect those actions.
-Consider the following BUILD file:
+Consider the following `BUILD` file:
```python
java_library(name = 'W', ...)
@@ -41,7 +41,7 @@
java_library(name = 'X', deps = [':Y',':Z'], runtime_deps = [':T'], ...)
```
-This BUILD file defines a dependency graph shown in the following figure:
+This `BUILD` file defines a dependency graph shown in the following figure:
<img src="build-graph.png" alt="Build Graph" width="250px" />
diff --git a/site/docs/skylark/build-style.md b/site/docs/skylark/build-style.md
index 860495e..b0a4d70 100644
--- a/site/docs/skylark/build-style.md
+++ b/site/docs/skylark/build-style.md
@@ -172,14 +172,14 @@
Do not use recursive globs to match source files (for example,
`glob(["**/*.java"])`).
-Recursive globs make BUILD files difficult to reason about because they skip
-subdirectories containing BUILD files.
+Recursive globs make `BUILD` files difficult to reason about because they skip
+subdirectories containing `BUILD` files.
-Recursive globs are generally less efficient than having a BUILD file per
+Recursive globs are generally less efficient than having a `BUILD` file per
directory with a dependency graph defined between them as this enables better
remote caching and parallelism.
-It is good practice to author a BUILD file in each directory and define a
+It is good practice to author a `BUILD` file in each directory and define a
dependency graph between them.
### Non-recursive
@@ -214,8 +214,8 @@
* No strict line length limit. Long comments and long strings are often split
to 79 columns, but it is not required. It should not be enforced in code
reviews or presubmit scripts. *Rationale*: Labels can be long and exceed this
- limit. It is common for `BUILD` files to be generated or edited by tools, which
- does not go well with a line length limit.
+ limit. It is common for `BUILD` files to be generated or edited by tools,
+ which does not go well with a line length limit.
* Implicit string concatenation is not supported. Use the `+` operator.
*Rationale*: `BUILD` files contain many string lists. It is easy to forget a
diff --git a/site/docs/skylark/bzl-style.md b/site/docs/skylark/bzl-style.md
index 65ae2a6..df26c06 100644
--- a/site/docs/skylark/bzl-style.md
+++ b/site/docs/skylark/bzl-style.md
@@ -14,30 +14,30 @@
language that defines how software is built, and as such it is both a
programming and a configuration language.
-You will use Starlark to write BUILD files, macros, and build rules. Macros and
-rules are essentially meta-languages - they define how BUILD files are written.
-BUILD files are intended to be simple and repetitive.
+You will use Starlark to write `BUILD` files, macros, and build rules. Macros and
+rules are essentially meta-languages - they define how `BUILD` files are written.
+`BUILD` files are intended to be simple and repetitive.
All software is read more often than it is written. This is especially true for
-Starlark, as engineers read BUILD files to understand dependencies of their
+Starlark, as engineers read `BUILD` files to understand dependencies of their
targets and details of their builds. This reading will often happen in passing,
in a hurry, or in parallel to accomplishing some other task. Consequently,
simplicity and readability are very important so that users can parse and
-comprehend BUILD files quickly.
+comprehend `BUILD` files quickly.
-When a user opens a BUILD file, they quickly want to know the list of targets in
+When a user opens a `BUILD` file, they quickly want to know the list of targets in
the file; or review the list of sources of that C++ library; or remove a
dependency from that Java binary. Each time you add a layer of abstraction, you
make it harder for a user to do these tasks.
-BUILD files are also analyzed and updated by many different tools. Tools may not
-be able to edit your BUILD file if it uses abstractions. Keeping your BUILD
+`BUILD` files are also analyzed and updated by many different tools. Tools may not
+be able to edit your `BUILD` file if it uses abstractions. Keeping your `BUILD`
files simple will allow you to get better tooling. As a code base grows, it
-becomes more and more frequent to do changes across many BUILD files in order to
+becomes more and more frequent to do changes across many `BUILD` files in order to
update a library or do a cleanup.
**IMPORTANT:** Do not create a variable or macro just to avoid some amount of
-repetition in BUILD files. Your BUILD file should be easily readable both by
+repetition in `BUILD` files. Your `BUILD` file should be easily readable both by
developers and tools. The
[DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) principle doesn't
really apply here.
@@ -78,7 +78,7 @@
### Line length
-As in BUILD files, there is no strict line length limit as labels can be long.
+As in `BUILD` files, there is no strict line length limit as labels can be long.
When possible, try to use at most 79 characters per line.
### Keyword arguments
@@ -125,7 +125,7 @@
depending on aspects (IDEs and others) might fail.
A safe use for macros is leaf nodes, such as macros defining test permutations:
-in that case, only the "end users" of those targets need to know about those
+in that case, only the *end users* of those targets need to know about those
additional nodes, and any build problems introduced by macros are never far from
their usage.
@@ -135,8 +135,8 @@
That target becomes that macro's _main target_.
* All other targets defined by a macro should have their names preceded with
an underscore (`_`), followed by the name attribute. For instance, if the
- macro is supplied with the name "resources", internal targets should have
- names beginning with "_resources". They should also have restricted
+ macro is supplied with the name *resources*, internal targets should have
+ names beginning with *_resources*. They should also have restricted
visibility.
* The `name` should only be used to derive names of targets defined by the
macro, and not for anything else. For example, don't use the name to derive
diff --git a/site/docs/skylark/concepts.md b/site/docs/skylark/concepts.md
index ad33856..4aec57d 100644
--- a/site/docs/skylark/concepts.md
+++ b/site/docs/skylark/concepts.md
@@ -16,19 +16,19 @@
Before learning the more advanced concepts, first:
-* Read about the [Starlark language](language.md), used in both the BUILD and
+* Read about the [Starlark language](language.md), used in both the `BUILD` and
`.bzl` files.
* Learn how you can [share variables](tutorial-sharing-variables.md) between two
- BUILD files.
+ `BUILD` files.
## Macros and rules
A [macro](macros.md) is a function that instantiates rules. It is useful when a
-BUILD file is getting too repetitive or too complex, as it allows you to reuse
-some code. The function is evaluated as soon as the BUILD file is read. After
-the evaluation of the BUILD file, Bazel has little information about macros: if
-your macro generates a `genrule`, Bazel will behave as if you wrote the
+`BUILD` file is getting too repetitive or too complex, as it allows you to reuse
+some code. The function is evaluated as soon as the `BUILD` file is read. After
+the evaluation of the `BUILD` file, Bazel has little information about macros:
+if your macro generates a `genrule`, Bazel will behave as if you wrote the
`genrule`. As a result, `bazel query` will only list the generated `genrule`.
A [rule](rules.md) is more powerful than a macro. It can access Bazel internals
@@ -45,8 +45,8 @@
A build consists of three phases.
-* **Loading phase**. First, load and evaluate all extensions and all BUILD
- files that are needed for the build. The execution of the BUILD files simply
+* **Loading phase**. First, load and evaluate all extensions and all `BUILD`
+ files that are needed for the build. The execution of the `BUILD` files simply
instantiates rules (each time a rule is called, it gets added to a graph).
This is where macros are evaluated.
diff --git a/site/docs/skylark/deploying.md b/site/docs/skylark/deploying.md
index 0e9e96c..5f44ba3 100644
--- a/site/docs/skylark/deploying.md
+++ b/site/docs/skylark/deploying.md
@@ -87,7 +87,7 @@
### README
At the top level, there should be a `README` that contains (at least) what
-users will need to copy-paste into their WORKSPACE file to use your rule.
+users will need to copy-paste into their `WORKSPACE` file to use your rule.
In general, this will be a `http_archive` pointing to your GitHub release and
a macro call that downloads/configures any tools your rule needs. For example,
for the [Go
@@ -109,7 +109,7 @@
If your rules depend on another repository's rules, specify that in the
rules documentation (for example, see the
[Skydoc rules](https://skydoc.bazel.build/docs/getting_started_stardoc.html),
-which depend on the Sass rules), and provide a WORKSPACE
+which depend on the Sass rules), and provide a `WORKSPACE`
macro that will download all dependencies (see `rules_go` above).
### Rules
@@ -149,7 +149,7 @@
for best practices, and to see what constraints are already present, and
consider contributing your constraints there if they are language independent.
Be mindful of introducing custom constraints, all users of your rules will
-use them to perform platform specific logic in their BUILD files (for example,
+use them to perform platform specific logic in their `BUILD` files (for example,
using [selects](https://docs.bazel.build/versions/master/be/functions.html#select)).
With custom constraints, you define a language that the whole Bazel ecosystem
will speak.
@@ -166,10 +166,10 @@
#### Dependencies
Your rules might have external dependencies. To make depending on your rules
-simpler, please provide a WORKSPACE macro that will declare dependencies on
+simpler, please provide a `WORKSPACE` macro that will declare dependencies on
those external dependencies. Do not declare dependencies of tests there, only
dependencies that rules require to work. Put development dependencies into the
-WORKSPACE file.
+`WORKSPACE` file.
Create a file named `<LANG>/repositories.bzl` and provide a single entry point
macro named `rules_<LANG>_dependencies`. Our directory will look as follows:
@@ -187,12 +187,12 @@
#### Registering toolchains
-Your rules might also register toolchains. Please provide a separate WORKSPACE
+Your rules might also register toolchains. Please provide a separate `WORKSPACE`
macro that registers these toolchains. This way users can decide to omit the
previous macro and control dependencies manually, while still being allowed to
register toolchains.
-Therefore add a WORKSPACE macro named `rules_<LANG>_toolchains` into
+Therefore add a `WORKSPACE` macro named `rules_<LANG>_toolchains` into
`<LANG>/repositories.bzl` file.
Note that in order to resolve toolchains in the analysis phase Bazel needs to
@@ -207,7 +207,7 @@
#### Release snippet
In your release announcement provide a snippet that your users can copy-paste
-into their WORKSPACE file. This snippet in general will look as follows:
+into their `WORKSPACE` file. This snippet in general will look as follows:
```
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
diff --git a/site/docs/skylark/language.md b/site/docs/skylark/language.md
index ab1b79c..4e8a3a5 100644
--- a/site/docs/skylark/language.md
+++ b/site/docs/skylark/language.md
@@ -107,7 +107,7 @@
* Global variables are immutable.
* `for` statements are not allowed at the top-level. Use them within functions
- instead. In BUILD files, you may use list comprehensions.
+ instead. In `BUILD` files, you may use list comprehensions.
* `if` statements are not allowed at the top-level. However, `if` expressions
can be used: `first = data[0] if len(data) > 0 else None`.
