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
This commit is contained in:
Chaitanya Varier
GitHub
parent
da6fb88da7
commit
6f7469dd03
|
|
@ -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",
|
||||
)
|
||||
|
|
|
|||
|
|
@ -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> |
|
||||
|
||||
|
||||
|
|
@ -102,12 +102,12 @@ Expand make variables and substitute like genrule does.
|
|||
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 @@ for more information of how these special variables are expanded.
|
|||
|
||||
**RETURNS**
|
||||
|
||||
s with the variables expanded
|
||||
`s` with the variables expanded
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -2,6 +2,9 @@
|
|||
|
||||
params_file public API
|
||||
|
||||
|
||||
|
||||
|
||||
<a id="#params_file"></a>
|
||||
|
||||
## params_file
|
||||
|
|
@ -15,16 +18,16 @@ Generates a UTF-8 encoded params file from a list of arguments.
|
|||
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 |
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,4 @@
|
|||
exports_files([
|
||||
"func_html.vm",
|
||||
"rule_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
|
||||
|
|
@ -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
|
||||
|
|
@ -14,6 +14,13 @@ filegroup(
|
|||
visibility = ["//:__pkg__"],
|
||||
)
|
||||
|
||||
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"],
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -20,34 +20,38 @@ def params_file(
|
|||
|
||||
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(
|
||||
|
|
|
|||
|
|
@ -23,6 +23,17 @@ bzl_library(
|
|||
deps = ["@bazel_skylib//lib:paths"],
|
||||
)
|
||||
|
||||
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"],
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
)
|
||||
|
|
@ -107,12 +107,12 @@ def expand_variables(ctx, s, outs = [], output_dir = False, attribute_name = "ar
|
|||
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 @@ def expand_variables(ctx, s, outs = [], output_dir = False, attribute_name = "ar
|
|||
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,
|
||||
|
|
|
|||
|
|
@ -45,7 +45,7 @@ def _to_label(param):
|
|||
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():
|
||||
|
|
|
|||
Loading…
Reference in New Issue