feat: add doc helpers (#2)
* add stardoc helpers
* fix incorrect default template in stardoc_with_diff_test()
* add stardoc helpers
* fix failing build for docs.md; add templates; cleanup
diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel
index 8b44c08..dce3886 100644
--- a/docs/BUILD.bazel
+++ b/docs/BUILD.bazel
@@ -1,56 +1,34 @@
# These loads are in the docs/ package rather than anything users depend on
# so that the dependency on stardoc doesn't leak to them.
-load("@bazel_skylib//rules:diff_test.bzl", "diff_test")
-load("@bazel_skylib//rules:write_file.bzl", "write_file")
-load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
+load("//lib:docs.bzl", "stardoc_with_diff_test", "update_docs")
-# Dictionary mapping from the label of a starlark module
-# (like //lib:some.bzl) to the markdown file in this
-# folder where the API docs are written.
-_DOCS = {
- "//lib:expand_make_vars.bzl": "expand_make_vars.md",
- "//lib:params_file.bzl": "params_file.md",
- "//lib:utils.bzl": "utils.md",
- "//lib:paths.bzl": "paths.md",
-}
-
-[
- stardoc(
- name = md + "_gen",
- out = md + "_",
- input = tgt,
- deps = [tgt.replace(".bzl", "")],
- )
- for [
- tgt,
- md,
- ] in _DOCS.items()
-]
-
-[
- diff_test(
- name = "check_" + md,
- failure_message = "Run bazel run //docs:update",
- file1 = md,
- file2 = md + "_",
- )
- for md in _DOCS.values()
-]
-
-write_file(
- name = "gen_update",
- out = "update.sh",
- content = [
- "#!/usr/bin/env bash",
- "cd $BUILD_WORKSPACE_DIRECTORY",
- ] + [
- "cp -fv bazel-bin/docs/{0}_ docs/{0}".format(md)
- for md in _DOCS.values()
- ],
+stardoc_with_diff_test(
+ bzl_library_target = "//lib:docs",
+ out_label = "//docs:docs.md",
)
-sh_binary(
+stardoc_with_diff_test(
+ bzl_library_target = "//lib:expand_make_vars",
+ out_label = "//docs:expand_make_vars.md",
+)
+
+stardoc_with_diff_test(
+ bzl_library_target = "//lib:params_file",
+ func_template = "//docs/templates:func_html.vm",
+ out_label = "//docs:params_file.md",
+)
+
+stardoc_with_diff_test(
+ bzl_library_target = "//lib:paths",
+ out_label = "//docs:paths.md",
+)
+
+stardoc_with_diff_test(
+ bzl_library_target = "//lib:utils",
+ out_label = "//docs:utils.md",
+)
+
+update_docs(
name = "update",
- srcs = ["update.sh"],
- data = [md + "_" for md in _DOCS.values()],
+ docs_folder = "docs",
)
diff --git a/docs/docs.md b/docs/docs.md
new file mode 100644
index 0000000..8cab261
--- /dev/null
+++ b/docs/docs.md
@@ -0,0 +1,65 @@
+<!-- Generated with Stardoc: http://skydoc.bazel.build -->
+
+Public API for docs helpers
+
+<a id="#stardoc_with_diff_test"></a>
+
+## stardoc_with_diff_test
+
+<pre>
+stardoc_with_diff_test(<a href="#stardoc_with_diff_test-bzl_library_target">bzl_library_target</a>, <a href="#stardoc_with_diff_test-out_label">out_label</a>, <a href="#stardoc_with_diff_test-aspect_template">aspect_template</a>, <a href="#stardoc_with_diff_test-func_template">func_template</a>,
+ <a href="#stardoc_with_diff_test-header_template">header_template</a>, <a href="#stardoc_with_diff_test-provider_template">provider_template</a>, <a href="#stardoc_with_diff_test-rule_template">rule_template</a>)
+</pre>
+
+Creates a stardoc target coupled with a `diff_test` for a given `bzl_library`.
+
+This is helpful for minimizing boilerplate in repos wih lots of stardoc targets.
+
+
+**PARAMETERS**
+
+
+| Name | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="stardoc_with_diff_test-bzl_library_target"></a>bzl_library_target | the label of the <code>bzl_library</code> target to generate documentation for | none |
+| <a id="stardoc_with_diff_test-out_label"></a>out_label | the label of the output MD file | none |
+| <a id="stardoc_with_diff_test-aspect_template"></a>aspect_template | the label or path to the Velocity aspect template to use with stardoc | <code>"@io_bazel_stardoc//stardoc:templates/markdown_tables/aspect.vm"</code> |
+| <a id="stardoc_with_diff_test-func_template"></a>func_template | the label or path to the Velocity function/macro template to use with stardoc | <code>"@io_bazel_stardoc//stardoc:templates/markdown_tables/func.vm"</code> |
+| <a id="stardoc_with_diff_test-header_template"></a>header_template | the label or path to the Velocity header template to use with stardoc | <code>"@io_bazel_stardoc//stardoc:templates/markdown_tables/header.vm"</code> |
+| <a id="stardoc_with_diff_test-provider_template"></a>provider_template | the label or path to the Velocity provider template to use with stardoc | <code>"@io_bazel_stardoc//stardoc:templates/markdown_tables/provider.vm"</code> |
+| <a id="stardoc_with_diff_test-rule_template"></a>rule_template | the label or path to the Velocity rule template to use with stardoc | <code>"@io_bazel_stardoc//stardoc:templates/markdown_tables/rule.vm"</code> |
+
+
+<a id="#update_docs"></a>
+
+## update_docs
+
+<pre>
+update_docs(<a href="#update_docs-name">name</a>, <a href="#update_docs-docs_folder">docs_folder</a>)
+</pre>
+
+Creates a `sh_binary` target which copies over generated doc files to the local source tree.
+
+This is to be used in tandem with `stardoc_with_diff_test()` to produce a convenient workflow
+for generating, testing, and updating all doc files as follows:
+
+``` bash
+bazel build //{docs_folder}/... && bazel test //{docs_folder}/... && bazel run //{docs_folder}:update
+```
+
+eg.
+
+``` bash
+bazel build //docs/... && bazel test //docs/... && bazel run //docs:update
+```
+
+
+**PARAMETERS**
+
+
+| Name | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="update_docs-name"></a>name | the name of the <code>sh_binary</code> target | <code>"update"</code> |
+| <a id="update_docs-docs_folder"></a>docs_folder | the name of the folder containing the doc files in the local source tree | <code>"docs"</code> |
+
+
diff --git a/docs/expand_make_vars.md b/docs/expand_make_vars.md
index 658fb15..2bbf881 100644
--- a/docs/expand_make_vars.md
+++ b/docs/expand_make_vars.md
@@ -102,12 +102,12 @@
This function is the same as ctx.expand_make_variables with the additional
genrule-like substitutions of:
- - $@: The output file if it is a single file. Else triggers a build error.
- - $(@D): The output directory. If there is only one file name in outs,
+ - `$@`: The output file if it is a single file. Else triggers a build error.
+ - `$(@D)`: The output directory. If there is only one file name in outs,
this expands to the directory containing that file. If there are multiple files,
this instead expands to the package's root directory in the bin tree,
even if all generated files belong to the same subdirectory!
- - $(RULEDIR): The output directory of the rule, that is, the directory
+ - `$(RULEDIR)`: The output directory of the rule, that is, the directory
corresponding to the name of the package containing the rule under the bin tree.
See https://docs.bazel.build/versions/main/be/general.html#genrule.cmd and
@@ -128,6 +128,6 @@
**RETURNS**
-s with the variables expanded
+`s` with the variables expanded
diff --git a/docs/params_file.md b/docs/params_file.md
index 11edf39..aca9ada 100644
--- a/docs/params_file.md
+++ b/docs/params_file.md
@@ -2,6 +2,9 @@
params_file public API
+
+
+
<a id="#params_file"></a>
## params_file
@@ -15,16 +18,16 @@
Handles variable substitutions for args.
-**PARAMETERS**
+### **Parameters**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="params_file-name"></a>name | Name of the rule. | none |
| <a id="params_file-out"></a>out | Path of the output file, relative to this package. | none |
-| <a id="params_file-args"></a>args | Arguments to concatenate into a params file.<br><br>Subject to 'Make variable' substitution. See https://docs.bazel.build/versions/main/be/make-variables.html.<br><br>1. Subject to predefined source/output path variables substitutions.<br><br>The predefined variables <code>execpath</code>, <code>execpaths</code>, <code>rootpath</code>, <code>rootpaths</code>, <code>location</code>, and <code>locations</code> take label parameters (e.g. <code>$(execpath //foo:bar)</code>) and substitute the file paths denoted by that label.<br><br>See https://docs.bazel.build/versions/main/be/make-variables.html#predefined_label_variables for more info.<br><br>NB: This $(location) substition returns the manifest file path which differs from the *_binary & *_test args and genrule bazel substitions. This will be fixed in a future major release. See docs string of <code>expand_location_into_runfiles</code> macro in <code>internal/common/expand_into_runfiles.bzl</code> for more info.<br><br>2. Subject to predefined variables & custom variable substitutions.<br><br>Predefined "Make" variables such as $(COMPILATION_MODE) and $(TARGET_CPU) are expanded. See https://docs.bazel.build/versions/main/be/make-variables.html#predefined_variables.<br><br>Custom variables are also expanded including variables set through the Bazel CLI with --define=SOME_VAR=SOME_VALUE. See https://docs.bazel.build/versions/main/be/make-variables.html#custom_variables.<br><br>Predefined genrule variables are not supported in this context. | <code>[]</code> |
-| <a id="params_file-data"></a>data | Data for $(location) expansions in args. | <code>[]</code> |
-| <a id="params_file-newline"></a>newline | Line endings to use. One of ["auto", "unix", "windows"].<br><br>"auto" for platform-determined "unix" for LF "windows" for CRLF | <code>"auto"</code> |
+| <a id="params_file-args"></a>args | Arguments to concatenate into a params file. Subject to 'Make variable' substitution. See https://docs.bazel.build/versions/main/be/make-variables.html. <ol> <li> Subject to predefined source/output path variables substitutions. The predefined variables `execpath`, `execpaths`, `rootpath`, `rootpaths`, `location`, and `locations` take label parameters (e.g. `$(execpath //foo:bar)`) and substitute the file paths denoted by that label. See https://docs.bazel.build/versions/main/be/make-variables.html#predefined_label_variables for more info. NB: This $(location) substition returns the manifest file path which differs from the `*_binary` & `*_test` args and genrule bazel substitions. This will be fixed in a future major release. See docs string of `expand_location_into_runfiles` macro in `internal/common/expand_into_runfiles.bzl` for more info.</li> <li>Subject to predefined variables & custom variable substitutions. Predefined "Make" variables such as `$(COMPILATION_MODE)` and `$(TARGET_CPU)` are expanded. See https://docs.bazel.build/versions/main/be/make-variables.html#predefined_variables. Custom variables are also expanded including variables set through the Bazel CLI with `--define=SOME_VAR=SOME_VALUE`. See https://docs.bazel.build/versions/main/be/make-variables.html#custom_variables. Predefined genrule variables are not supported in this context.</li> </ol> | <code>[]</code> |
+| <a id="params_file-data"></a>data | Data for <code>$(location)</code> expansions in args. | <code>[]</code> |
+| <a id="params_file-newline"></a>newline | Line endings to use. One of [`"auto"`, `"unix"`, `"windows"`]. <ul> <li>`"auto"` for platform-determined</li> <li>`"unix"` for LF</li> <li>`"windows"` for CRLF</li> </ul> | <code>"auto"</code> |
| <a id="params_file-kwargs"></a>kwargs | undocumented named arguments | none |
diff --git a/docs/templates/BUILD.bazel b/docs/templates/BUILD.bazel
new file mode 100644
index 0000000..9a734fe
--- /dev/null
+++ b/docs/templates/BUILD.bazel
@@ -0,0 +1,4 @@
+exports_files([
+ "func_html.vm",
+ "rule_html.vm",
+])
diff --git a/docs/templates/func_html.vm b/docs/templates/func_html.vm
new file mode 100644
index 0000000..9809a4e
--- /dev/null
+++ b/docs/templates/func_html.vm
@@ -0,0 +1,49 @@
+#**
+This func template is used for rendering HTML in parameter table cells
+*#
+#*
+Workaround for markdownCellFormat() not allowing HTML (specifically lists) to be rendered in attribute table cells.
+
+TODO: Once https://github.com/bazelbuild/bazel/pull/14230 is merged, remove this macro and replace with call to
+ util.markdownCellFormatWithHtml($attribute.docString, true)
+*#
+#macro( markdownCellFormatNoEscapeHtml $docString )#*
+ *##if ($docString.contains("<ul>") || $docString.contains("<ol>"))#*
+ *#${docString.trim().replaceAll("\n(\\s*\n)+", "<br><br>").replaceAll("\n", " ")}#*
+ *##else#*
+ *#${util.markdownCellFormat($docString)}#*
+ *##end#*
+*##end
+
+<a id="#${funcInfo.functionName}"></a>
+
+#[[##]]# ${funcInfo.functionName}
+
+<pre>
+${util.funcSummary($funcInfo)}
+</pre>
+
+${funcInfo.docString}
+
+#if (!$funcInfo.getParameterList().isEmpty())
+#[[###]]# **Parameters**
+
+
+| Name | Description | Default Value |
+| :------------- | :------------- | :------------- |
+#foreach ($param in $funcInfo.getParameterList())
+| <a id="${funcInfo.functionName}-${param.name}"></a>$param.name | #if(!$param.docString.isEmpty()) #markdownCellFormatNoEscapeHtml( $param.docString ) #else <p align="center"> - </p> #end | #if(!$param.getDefaultValue().isEmpty()) <code>$param.getDefaultValue()</code> #else none #end|
+#end
+#end
+#if (!$funcInfo.getReturn().docString.isEmpty())
+
+#[[###]]# **Returns**
+
+${funcInfo.getReturn().docString}
+#end
+#if (!$funcInfo.getDeprecated().docString.isEmpty())
+
+#[[###]]# **Deprecated**
+
+${funcInfo.getDeprecated().docString}
+#end
\ No newline at end of file
diff --git a/docs/templates/rule_html.vm b/docs/templates/rule_html.vm
new file mode 100644
index 0000000..09d259c
--- /dev/null
+++ b/docs/templates/rule_html.vm
@@ -0,0 +1,37 @@
+#**
+This rule template is used for rendering HTML in attribute table cells
+*#
+#*
+Workaround for markdownCellFormat() not allowing HTML (specifically lists) to be rendered in attribute table cells.
+
+TODO: Once https://github.com/bazelbuild/bazel/pull/14230 is merged, remove this macro and replace with call to
+ util.markdownCellFormatWithHtml($attribute.docString, true)
+*#
+#macro( markdownCellFormatNoEscapeHtml $docString )#*
+ *##if ($docString.contains("<ul>") || $docString.contains("<ol>"))#*
+ *#${docString.trim().replaceAll("\n(\\s*\n)+", "<br><br>").replaceAll("\n", " ")}#*
+ *##else#*
+ *#${util.markdownCellFormat($docString)}#*
+ *##end#*
+*##end
+
+<a id="#${ruleName}"></a>
+
+#[[##]]# ${ruleName}
+
+<pre>
+${util.ruleSummary($ruleName, $ruleInfo)}
+</pre>
+
+${ruleInfo.docString}
+
+#[[###]]# **Attributes**
+
+#if (!$ruleInfo.getAttributeList().isEmpty())
+
+| Name | Description | Type | Mandatory | Default |
+| :------------- | :------------- | :------------- | :------------- | :------------- |
+#foreach ($attribute in $ruleInfo.getAttributeList())
+| <a id="${ruleName}-${attribute.name}"></a>$attribute.name | #if(!$attribute.docString.isEmpty()) #markdownCellFormatNoEscapeHtml( $attribute.docString ) #else - #end | ${util.attributeTypeString($attribute)} | ${util.mandatoryString($attribute)} | $attribute.defaultValue |
+#end
+#end
\ No newline at end of file
diff --git a/lib/BUILD.bazel b/lib/BUILD.bazel
index 29e6f4a..d88f473 100644
--- a/lib/BUILD.bazel
+++ b/lib/BUILD.bazel
@@ -15,6 +15,13 @@
)
bzl_library(
+ name = "docs",
+ srcs = ["docs.bzl"],
+ visibility = ["//visibility:public"],
+ deps = ["//lib/private:docs"],
+)
+
+bzl_library(
name = "expand_make_vars",
srcs = ["expand_make_vars.bzl"],
visibility = ["//visibility:public"],
diff --git a/lib/docs.bzl b/lib/docs.bzl
new file mode 100644
index 0000000..0bda36c
--- /dev/null
+++ b/lib/docs.bzl
@@ -0,0 +1,10 @@
+"Public API for docs helpers"
+
+load(
+ "//lib/private:docs.bzl",
+ _stardoc_with_diff_test = "stardoc_with_diff_test",
+ _update_docs = "update_docs",
+)
+
+stardoc_with_diff_test = _stardoc_with_diff_test
+update_docs = _update_docs
diff --git a/lib/params_file.bzl b/lib/params_file.bzl
index 4567995..eeee981 100644
--- a/lib/params_file.bzl
+++ b/lib/params_file.bzl
@@ -20,34 +20,38 @@
Subject to 'Make variable' substitution. See https://docs.bazel.build/versions/main/be/make-variables.html.
- 1. Subject to predefined source/output path variables substitutions.
+ <ol>
+ <li> Subject to predefined source/output path variables substitutions.
The predefined variables `execpath`, `execpaths`, `rootpath`, `rootpaths`, `location`, and `locations` take
label parameters (e.g. `$(execpath //foo:bar)`) and substitute the file paths denoted by that label.
See https://docs.bazel.build/versions/main/be/make-variables.html#predefined_label_variables for more info.
- NB: This $(location) substition returns the manifest file path which differs from the *_binary & *_test
+ NB: This $(location) substition returns the manifest file path which differs from the `*_binary` & `*_test`
args and genrule bazel substitions. This will be fixed in a future major release.
See docs string of `expand_location_into_runfiles` macro in `internal/common/expand_into_runfiles.bzl`
- for more info.
+ for more info.</li>
- 2. Subject to predefined variables & custom variable substitutions.
+ <li>Subject to predefined variables & custom variable substitutions.
- Predefined "Make" variables such as $(COMPILATION_MODE) and $(TARGET_CPU) are expanded.
+ Predefined "Make" variables such as `$(COMPILATION_MODE)` and `$(TARGET_CPU)` are expanded.
See https://docs.bazel.build/versions/main/be/make-variables.html#predefined_variables.
- Custom variables are also expanded including variables set through the Bazel CLI with --define=SOME_VAR=SOME_VALUE.
+ Custom variables are also expanded including variables set through the Bazel CLI with `--define=SOME_VAR=SOME_VALUE`.
See https://docs.bazel.build/versions/main/be/make-variables.html#custom_variables.
- Predefined genrule variables are not supported in this context.
+ Predefined genrule variables are not supported in this context.</li>
+ </ol>
- data: Data for $(location) expansions in args.
- newline: Line endings to use. One of ["auto", "unix", "windows"].
+ data: Data for `$(location)` expansions in args.
+ newline: Line endings to use. One of [`"auto"`, `"unix"`, `"windows"`].
- "auto" for platform-determined
- "unix" for LF
- "windows" for CRLF
+ <ul>
+ <li>`"auto"` for platform-determined</li>
+ <li>`"unix"` for LF</li>
+ <li>`"windows"` for CRLF</li>
+ </ul>
**kwargs: undocumented named arguments
"""
_params_file(
diff --git a/lib/private/BUILD.bazel b/lib/private/BUILD.bazel
index e1da0a1..d50cb41 100644
--- a/lib/private/BUILD.bazel
+++ b/lib/private/BUILD.bazel
@@ -24,6 +24,17 @@
)
bzl_library(
+ name = "docs",
+ srcs = ["docs.bzl"],
+ visibility = ["//lib:__subpackages__"],
+ deps = [
+ "@bazel_skylib//rules:diff_test",
+ "@bazel_skylib//rules:write_file",
+ "@io_bazel_stardoc//stardoc:stardoc_lib",
+ ],
+)
+
+bzl_library(
name = "expand_make_vars",
srcs = ["expand_make_vars.bzl"],
visibility = ["//lib:__subpackages__"],
diff --git a/lib/private/docs.bzl b/lib/private/docs.bzl
new file mode 100644
index 0000000..f5fad1c
--- /dev/null
+++ b/lib/private/docs.bzl
@@ -0,0 +1,98 @@
+"Helpers for generating stardoc documentation"
+
+load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
+load("@bazel_skylib//rules:write_file.bzl", "write_file")
+load("@bazel_skylib//rules:diff_test.bzl", "diff_test")
+
+def stardoc_with_diff_test(
+ bzl_library_target,
+ out_label,
+ aspect_template = "@io_bazel_stardoc//stardoc:templates/markdown_tables/aspect.vm",
+ func_template = "@io_bazel_stardoc//stardoc:templates/markdown_tables/func.vm",
+ header_template = "@io_bazel_stardoc//stardoc:templates/markdown_tables/header.vm",
+ provider_template = "@io_bazel_stardoc//stardoc:templates/markdown_tables/provider.vm",
+ rule_template = "@io_bazel_stardoc//stardoc:templates/markdown_tables/rule.vm"):
+ """Creates a stardoc target coupled with a `diff_test` for a given `bzl_library`.
+
+ This is helpful for minimizing boilerplate in repos wih lots of stardoc targets.
+
+ Args:
+ bzl_library_target: the label of the `bzl_library` target to generate documentation for
+ out_label: the label of the output MD file
+ aspect_template: the label or path to the Velocity aspect template to use with stardoc
+ func_template: the label or path to the Velocity function/macro template to use with stardoc
+ header_template: the label or path to the Velocity header template to use with stardoc
+ provider_template: the label or path to the Velocity provider template to use with stardoc
+ rule_template: the label or path to the Velocity rule template to use with stardoc
+ """
+
+ out_file = out_label.replace("//", "").replace(":", "/")
+
+ # Generate MD from .bzl
+ stardoc(
+ name = out_file.replace("/", "_").replace(".md", "-docgen"),
+ out = out_file.replace(".md", "-docgen.md"),
+ input = bzl_library_target + ".bzl",
+ deps = [bzl_library_target],
+ aspect_template = aspect_template,
+ func_template = func_template,
+ header_template = header_template,
+ provider_template = provider_template,
+ rule_template = rule_template,
+ )
+
+ # Ensure that the generated MD has been updated in the local source tree
+ diff_test(
+ name = out_file.replace("/", "_").replace(".md", "-difftest"),
+ failure_message = "Please run \"bazel run //docs:update\"",
+ # Source file
+ file1 = out_label,
+ # Output from stardoc rule above
+ file2 = out_file.replace(".md", "-docgen.md"),
+ )
+
+def update_docs(
+ name = "update",
+ docs_folder = "docs"):
+ """Creates a `sh_binary` target which copies over generated doc files to the local source tree.
+
+ This is to be used in tandem with `stardoc_with_diff_test()` to produce a convenient workflow
+ for generating, testing, and updating all doc files as follows:
+
+ ``` bash
+ bazel build //{docs_folder}/... && bazel test //{docs_folder}/... && bazel run //{docs_folder}:update
+ ```
+
+ eg.
+
+ ``` bash
+ bazel build //docs/... && bazel test //docs/... && bazel run //docs:update
+ ```
+
+ Args:
+ name: the name of the `sh_binary` target
+ docs_folder: the name of the folder containing the doc files in the local source tree
+ """
+ content = ["#!/usr/bin/env bash", "cd ${BUILD_WORKSPACE_DIRECTORY}"]
+ data = []
+ for r in native.existing_rules().values():
+ if r["kind"] == "stardoc":
+ doc_gen = r["out"]
+ if doc_gen.startswith(":"):
+ doc_gen = doc_gen[1:]
+ doc_dest = doc_gen.replace("-docgen.md", ".md")
+ data.append(doc_gen)
+ content.append("cp -fv bazel-bin/{0}/{1} {2}".format(docs_folder, doc_gen, doc_dest))
+
+ update_script = name + ".sh"
+ write_file(
+ name = "gen_" + name,
+ out = update_script,
+ content = content,
+ )
+
+ native.sh_binary(
+ name = name,
+ srcs = [update_script],
+ data = data,
+ )
diff --git a/lib/private/expand_make_vars.bzl b/lib/private/expand_make_vars.bzl
index f45cfc8..f3afe3d 100644
--- a/lib/private/expand_make_vars.bzl
+++ b/lib/private/expand_make_vars.bzl
@@ -107,12 +107,12 @@
This function is the same as ctx.expand_make_variables with the additional
genrule-like substitutions of:
- - $@: The output file if it is a single file. Else triggers a build error.
- - $(@D): The output directory. If there is only one file name in outs,
+ - `$@`: The output file if it is a single file. Else triggers a build error.
+ - `$(@D)`: The output directory. If there is only one file name in outs,
this expands to the directory containing that file. If there are multiple files,
this instead expands to the package's root directory in the bin tree,
even if all generated files belong to the same subdirectory!
- - $(RULEDIR): The output directory of the rule, that is, the directory
+ - `$(RULEDIR)`: The output directory of the rule, that is, the directory
corresponding to the name of the package containing the rule under the bin tree.
See https://docs.bazel.build/versions/main/be/general.html#genrule.cmd and
@@ -127,7 +127,7 @@
attribute_name: name of the attribute containing the expression
Returns:
- s with the variables expanded
+ `s` with the variables expanded
"""
rule_dir = [f for f in [
ctx.bin_dir.path,
diff --git a/lib/private/utils.bzl b/lib/private/utils.bzl
index 6ac768e..da4d653 100644
--- a/lib/private/utils.bzl
+++ b/lib/private/utils.bzl
@@ -45,7 +45,7 @@
if not param.startswith("@") and not param.startswith("//"):
# resolve the relative label from the current package
# if 'param' is in another workspace, then this would return the label relative to that workspace, eg:
- # Label("@my//foo:bar").relative("@other//baz:bill") == Label("@other//baz:bill")
+ # `Label("@my//foo:bar").relative("@other//baz:bill") == Label("@other//baz:bill")`
if param.startswith(":"):
param = param[1:]
if native.package_name():
