docs: add outputs example
diff --git a/examples/substitutions/BUILD.bazel b/examples/substitutions/BUILD.bazel index 399096d..ef86d69 100644 --- a/examples/substitutions/BUILD.bazel +++ b/examples/substitutions/BUILD.bazel
@@ -3,6 +3,106 @@ load("@bazel_skylib//rules:common_settings.bzl", "string_flag") genrule( + name = "header", + outs = ["header.html"], + cmd = """echo ' +<!DOCTYPE html + PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> + +<body> + <a href="https://github.com/TendTo/rules_doxygen" class="github-corner" title="View source on GitHub" target="_blank" + rel="noopener noreferrer"> + <svg viewBox="0 0 250 250" width="40" height="40" + style="position: absolute; top: 0; border: 0; right: 0; z-index: 99" aria-hidden="true"> + <path d="M0,0 L115,115 L130,115 L142,142 L250,250 L250,0 Z"></path> + <path + d="M128.3,109.0 C113.8,99.7 119.0,89.6 119.0,89.6 C122.0,82.7 120.5,78.6 120.5,78.6 C119.2,72.0 123.4,76.3 123.4,76.3 C127.3,80.9 125.5,87.3 125.5,87.3 C122.9,97.6 130.6,101.9 134.4,103.2" + fill="currentColor" style="transform-origin: 130px 106px" class="octo-arm"></path> + <path + d="M115.0,115.0 C114.9,115.1 118.7,116.5 119.8,115.4 L133.7,101.6 C136.9,99.2 139.9,98.4 142.2,98.6 C133.8,88.0 127.5,74.4 143.8,58.0 C148.5,53.4 154.0,51.2 159.7,51.0 C160.3,49.4 163.2,43.6 171.4,40.1 C171.4,40.1 176.1,42.5 178.8,56.2 C183.1,58.6 187.2,61.8 190.9,65.4 C194.5,69.0 197.7,73.2 200.1,77.6 C213.8,80.2 216.3,84.9 216.3,84.9 C212.7,93.1 206.9,96.0 205.4,96.6 C205.1,102.4 203.0,107.8 198.3,112.5 C181.9,128.9 168.3,122.5 157.7,114.1 C157.9,116.9 156.7,120.9 152.7,124.9 L141.0,136.5 C139.8,137.7 141.6,141.9 141.8,141.8 Z" + fill="currentColor" class="octo-body"></path> + </svg></a> + <style> + .github-corner:hover .octo-arm { + animation: octocat-wave 560ms ease-in-out; + } + + @keyframes octocat-wave { + + 0%, + 100% { + transform: rotate(0); + } + + 20%, + 60% { + transform: rotate(-25deg); + } + + 40%, + 80% { + transform: rotate(10deg); + } + } + + @media (max-width: 500px) { + .github-corner:hover .octo-arm { + animation: none; + } + + .github-corner .octo-arm { + animation: octocat-wave 560ms ease-in-out; + } + } + </style> + + <div id="top"> + <!-- do not remove this div, it is closed by doxygen! --> + + <!--BEGIN TITLEAREA--> + <div id="titlearea"> + <table cellspacing="0" cellpadding="0"> + <tbody> + <tr style="height: 56px"> + <!--BEGIN PROJECT_LOGO--> + <td id="projectlogo"> + <img alt="Logo" src="$$relpath^$$projectlogo" /> + </td> + <!--END PROJECT_LOGO--> + <!--BEGIN PROJECT_NAME--> + <td id="projectalign" style="padding-left: 0.5em"> + <div id="projectname"> + $$projectname + <!--BEGIN PROJECT_NUMBER--> <span id="projectnumber">$$projectnumber</span><!--END PROJECT_NUMBER--> + </div> + <!--BEGIN PROJECT_BRIEF--> + <div id="projectbrief">$$projectbrief</div> + <!--END PROJECT_BRIEF--> + </td> + <!--END PROJECT_NAME--> + <!--BEGIN !PROJECT_NAME--> + <!--BEGIN PROJECT_BRIEF--> + <td style="padding-left: 0.5em"> + <div id="projectbrief">$$projectbrief</div> + </td> + <!--END PROJECT_BRIEF--> + <!--END !PROJECT_NAME--> + <!--BEGIN DISABLE_INDEX--> + <!--BEGIN SEARCHENGINE--> + <td>$$searchbox</td> + <!--END SEARCHENGINE--> + <!--END DISABLE_INDEX--> + </tr> + </tbody> + </table> + </div> + <!--END TITLEAREA--> + <!-- end header part --> + ' > $@""", +) + +genrule( name = "doxyfile_template", srcs = ["Doxyfile.template"], outs = ["NewDoxyfile"], @@ -18,6 +118,9 @@ make_var_substitution( name = "make_var_substitution", + locations = { + "HEADER": ":header", + }, variables = { "NAME": "substitutions", }, @@ -28,9 +131,17 @@ srcs = glob([ "*.h", "*.cpp", - ]), + ]) + [":header"], doxyfile_template = ":doxyfile_template", + html_header = "$(HEADER)", project_brief = "$(BUILD_DESCRIPTION)", project_name = "$(NAME)", toolchains = [":make_var_substitution"], ) + +genrule( + name = "doxygen_files", + srcs = [":doxygen"], + outs = ["doxygen_files.txt"], + cmd = "ls $(location :doxygen) > $@", +) \ No newline at end of file
diff --git a/examples/substitutions/README.md b/examples/substitutions/README.md index 7092fb1..cb6c23c 100644 --- a/examples/substitutions/README.md +++ b/examples/substitutions/README.md
@@ -68,11 +68,15 @@ vars["BUILD_DESCRIPTION"] = ctx.attr._build_description[BuildSettingInfo].value else: # Otherwise use the hardcoded value. vars["BUILD_DESCRIPTION"] = "no stamp" + # Add the path of the label files to the variables. + for key, value in ctx.attr.locations.items(): + vars[key] = '"%s"' % '" "'.join([file.path for file in (value[DefaultInfo].files.to_list())]) return [platform_common.TemplateVariableInfo(vars)] make_var_substitution = rule( implementation = _make_var_substitution_impl, attrs = dict({ + "locations": attr.string_keyed_label_dict(), "variables": attr.string_dict(), "_build_description": attr.label(default = "//substitutions:build_description"), }, **STAMP_ATTRS), @@ -103,6 +107,23 @@ ) ``` +### Output files + +It is also possible to use files produced by other rules as input files for the doxygen rule. +For example, we can use a `genrule` to create an `header.html` file that will be used as the header for the doxygen documentation. + +```bzl +# BUILD.bazel +genrule( + name = "header", + srcs = ["header.html"], + outs = ["header.html"], + cmd = "echo '<h1>My Header</h1>' > $@", +) +``` + +We need to include the genrule in the `locations` attribute of a `make_var_substitution` rule, as well as including it in the `srcs` attribute of the doxygen rule and specifying the location substitution in the `doxygen` rule. + ### Final result ```bzl @@ -111,6 +132,14 @@ load("@doxygen//:doxygen.bzl", "doxygen") load("//substitutions:make_var_substitution.bzl", "make_var_substitution") +# Use a shell script to create a header file +genrule( + name = "header", + srcs = ["header.html"], + outs = ["header.html"], + cmd = "echo '<h1>My Header</h1>' > $@", +) + # Use a shell script to read the version from the stable-status.txt file # It will replace the pattern {{PROJECT_NUMBER}} in the Doxyfile.template file genrule( @@ -128,6 +157,9 @@ variables = { "NAME": "substitutions", }, + locations = { + "HEADER": ":header", + }, ) doxygen( @@ -135,10 +167,11 @@ srcs = glob([ "*.h", "*.cpp", - ]), - project_brief = "$(DESCRIPTION)", # => "no stamp" or "//substitutions:build_description" if the build is stamped + ]) + [":header"], # We need to indicate all the rules this doxygen rule depends on + project_brief = "$(BUILD_DESCRIPTION)", # => "no stamp" or "//substitutions:build_description" if the build is stamped project_name = "$(NAME)", # => "substitutions" doxyfile_template = ":doxyfile_template", + html_header = "$(HEADER)", # => "header.html" toolchains = [":make_var_substitution"], ) ```
diff --git a/examples/substitutions/make_var_substitution.bzl b/examples/substitutions/make_var_substitution.bzl index 517ca92..9570513 100644 --- a/examples/substitutions/make_var_substitution.bzl +++ b/examples/substitutions/make_var_substitution.bzl
@@ -8,11 +8,15 @@ vars["BUILD_DESCRIPTION"] = ctx.attr._build_description[BuildSettingInfo].value else: # Otherwise use the hardcoded value. vars["BUILD_DESCRIPTION"] = "no stamp" + # Add the path of the label files to the variables. + for key, value in ctx.attr.locations.items(): + vars[key] = '"%s"' % '" "'.join([file.path for file in (value[DefaultInfo].files.to_list())]) return [platform_common.TemplateVariableInfo(vars)] make_var_substitution = rule( implementation = _make_var_substitution_impl, attrs = dict({ + "locations": attr.string_keyed_label_dict(), "variables": attr.string_dict(), "_build_description": attr.label(default = "//substitutions:build_description"), }, **STAMP_ATTRS), @@ -25,22 +29,34 @@ Example: ```bzl +filegroup( + name = "header", + srcs = ["header.html"], +) + make_var_substitution( variables = { "MY_VARIABLE": "my_value", "VERSION": "1.0.0", }, + locations = { + "HEADER": ":header", + }, ) doxygen( name = "doxygen", - srcs = ["main.cpp"], + srcs = ["main.cpp", ":header"], project_brief = "$(MY_VARIABLE)", # => "my_value" project_number = "$(VERSION)", # => "1.0.0" + html_header = "$(HEADER)", # => "header.html" toolchains = [":make_var_substitution"], ) ``` -This will make the variable `MY_VARIABLE` available to the template engine. +This will make the variable `MY_VARIABLE` available to the template engine +and replace it with the value `my_value` in the generated files. +It will also make the variable `HEADER` available to the template engine +and replace it with the path to the file `header.html` generated by the rule `header`. """, )