From 6f7469dd03dd1a19697a3d7e33d7ba8972eac034 Mon Sep 17 00:00:00 2001 From: Chaitanya Varier Date: Wed, 10 Nov 2021 09:34:00 -0500 Subject: [PATCH] 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 --- docs/BUILD.bazel | 76 +++++++++---------------- docs/docs.md | 65 +++++++++++++++++++++ docs/expand_make_vars.md | 8 +-- docs/params_file.md | 11 ++-- docs/templates/BUILD.bazel | 4 ++ docs/templates/func_html.vm | 49 ++++++++++++++++ docs/templates/rule_html.vm | 37 ++++++++++++ lib/BUILD.bazel | 7 +++ lib/docs.bzl | 10 ++++ lib/params_file.bzl | 28 +++++---- lib/private/BUILD.bazel | 11 ++++ lib/private/docs.bzl | 98 ++++++++++++++++++++++++++++++++ lib/private/expand_make_vars.bzl | 8 +-- lib/private/utils.bzl | 2 +- 14 files changed, 340 insertions(+), 74 deletions(-) create mode 100644 docs/docs.md create mode 100644 docs/templates/BUILD.bazel create mode 100644 docs/templates/func_html.vm create mode 100644 docs/templates/rule_html.vm create mode 100644 lib/docs.bzl create mode 100644 lib/private/docs.bzl 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 @@ + + +Public API for docs helpers + + + +## stardoc_with_diff_test + +
+stardoc_with_diff_test(bzl_library_target, out_label, aspect_template, func_template,
+                       header_template, provider_template, rule_template)
+
+ +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 | +| :------------- | :------------- | :------------- | +| bzl_library_target | the label of the bzl_library target to generate documentation for | none | +| out_label | the label of the output MD file | none | +| aspect_template | the label or path to the Velocity aspect template to use with stardoc | "@io_bazel_stardoc//stardoc:templates/markdown_tables/aspect.vm" | +| func_template | the label or path to the Velocity function/macro template to use with stardoc | "@io_bazel_stardoc//stardoc:templates/markdown_tables/func.vm" | +| header_template | the label or path to the Velocity header template to use with stardoc | "@io_bazel_stardoc//stardoc:templates/markdown_tables/header.vm" | +| provider_template | the label or path to the Velocity provider template to use with stardoc | "@io_bazel_stardoc//stardoc:templates/markdown_tables/provider.vm" | +| rule_template | the label or path to the Velocity rule template to use with stardoc | "@io_bazel_stardoc//stardoc:templates/markdown_tables/rule.vm" | + + + + +## update_docs + +
+update_docs(name, docs_folder)
+
+ +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 | +| :------------- | :------------- | :------------- | +| name | the name of the sh_binary target | "update" | +| docs_folder | the name of the folder containing the doc files in the local source tree | "docs" | + + 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 @@ 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 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 + + + ## 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 | | :------------- | :------------- | :------------- | | name | Name of the rule. | none | | out | Path of the output file, relative to this package. | none | -| args | Arguments to concatenate into a 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.

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.

2. 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. | [] | -| 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 | "auto" | +| args | Arguments to concatenate into a 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. 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.
  2. 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.
| [] | +| data | Data for $(location) expansions in args. | [] | +| newline | Line endings to use. One of [`"auto"`, `"unix"`, `"windows"`]. | "auto" | | 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("