docs: add outputs example

TendTo · TendTo · commit b080834cd041 · 2025-04-02T00:53:52.000+02:00
diff --git a/examples/substitutions/BUILD.bazel b/examples/substitutions/BUILD.bazel
@@ -2,6 +2,106 @@ load("@doxygen//:doxygen.bzl", "doxygen")
 load("//substitutions:make_var_substitution.bzl", "make_var_substitution")
 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-->&#160;<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"],
@@ -18,6 +118,9 @@ string_flag(
 
 make_var_substitution(
     name = "make_var_substitution",
+    locations = {
+        "HEADER": ":header",
+    },
     variables = {
         "NAME": "substitutions",
     },
@@ -28,9 +131,17 @@ doxygen(
     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) > $@",
+)
diff --git a/examples/substitutions/README.md b/examples/substitutions/README.md
@@ -68,11 +68,15 @@ def _make_var_substitution_impl(ctx):
         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 @@ genrule(
 )
 ```
 
+### 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 @@ genrule(
 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,17 +157,21 @@ make_var_substitution(
     variables = {
         "NAME": "substitutions",
     },
+    locations = {
+        "HEADER": ":header",
+    },
 )
 
 doxygen(
     name = "doxygen",
     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
@@ -8,11 +8,15 @@ def _make_var_substitution_impl(ctx):
         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 @@ It provides the following substitution variables by default:
 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`.
 """,
 )
