bazel/bazel-lib
2
0
Fork 0
mirror of https://github.com/bazel-contrib/bazel-lib synced 2024-11-26 13:30:30 +00:00
Code Issues Releases Activity
bazel-lib/docs/docs.md
Chaitanya Varier 6f7469dd03
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
2021-11-10 06:34:00 -08:00

3.3 KiB
Raw Blame History

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:

bazel build //{docs_folder}/... && bazel test //{docs_folder}/... && bazel run //{docs_folder}:update

eg.

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"