diff options
author | dzc <dzc@google.com> | 2017-05-31 20:37:50 +0200 |
---|---|---|
committer | László Csomor <laszlocsomor@google.com> | 2017-06-01 14:07:52 +0200 |
commit | 22b85a2a3c79c6f3aef1e0a61e485bb135be4551 (patch) | |
tree | 8235e8237b171ced2fa9f39f054f9a7d808c0771 /site/docs/skylark/bzl-style.md | |
parent | 40d64293b57f0d62bb15599c730f38484b91d3f0 (diff) |
Restructure site/ directory into docs/ which only contains Bazel documentation.
The new docs/ directory in the bazel source tree will only contain the Bazel
docs site, which is hosted at docs.bazel.build. This change deletes the
marketing site and blog, which have been migrated to the bazel-website and
bazel-blog GitHub repositories respectively.
This change also updates the serve-docs.sh and ci/build.sh under scripts/ in
preparation for publishing the docs site.
Note that to help make reviews more manageable, this change is limited to
moving files to their new locations. Here are the follow-up changes:
* Update all links in docs to remove versions/master in paths and to add
correct bazel.build subdomain when linking to pages on the marketing site
or the blog.
* Set up versioned directories on GCS bucket and add tooling for versioning
docs
This change is also coordinated with
https://bazel-review.googlesource.com/c/11568/ to have the PublishSite job
publish to docs.bazel.build rather than www.bazel.build.
Issue #2397
RELNOTES: None
PiperOrigin-RevId: 157612651
Diffstat (limited to 'site/docs/skylark/bzl-style.md')
-rw-r--r-- | site/docs/skylark/bzl-style.md | 52 |
1 files changed, 50 insertions, 2 deletions
diff --git a/site/docs/skylark/bzl-style.md b/site/docs/skylark/bzl-style.md index c17600796b..66c2d2918e 100644 --- a/site/docs/skylark/bzl-style.md +++ b/site/docs/skylark/bzl-style.md @@ -1,4 +1,52 @@ --- -layout: redirect -redirect: docs/skylark/bzl-style.html +layout: documentation +title: Style guide for bzl files --- + +# .bzl file style guide + +## Style + +* When in doubt, follow the + [Python style guide](https://www.python.org/dev/peps/pep-0008/). + +* Code should be documented using + [docstrings](https://www.python.org/dev/peps/pep-0257/). Use a docstring at + the top of the file, and a docstring for each public function. + +* Variables and function names use lowercase with words separated by underscores + (`[a-z][a-z0-9_]*`), e.g. `cc_library`. Top-level private values start with + one underscore. Bazel enforces that private values cannot be used from other + files. + +* 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. + +* In keyword arguments, spaces around the equal sign are optional. In general, + we follow the BUILD file convention when calling macros and native rules, and + the Python convention for other functions, e.g. + +```python +def fct(name, srcs): + filtered_srcs = my_filter(source=srcs) + native.cc_library( + name = name, + srcs = filtered_srcs, + ) +``` + +## Macros + +A [macro](macros.md) is a function which instantiates one or many rules during +the loading phase. + +* Macros must accept a name attribute and each invocation should specify a name. + The generated name attribute of rules should include the name attribute as a + prefix. For example, `my_macro(name = "foo")` can generate a rule `foo` and a + rule `foo_gen`. *Rationale*: Users should be able to find easily which macro + generated a rule. Also, automated refactoring tools need a way to identify a + specific rule to edit. + +* When calling a macro, use only keyword arguments. *Rationale*: This is for + consistency with rules, it greatly improves readability. + |