Merge pull request #28 from TendTo/feat/custom-outputs

TendTo · web-flow · commit 769ba47a85fe · 2025-06-21T12:11:15.000+01:00
Feat: custom outputs
diff --git a/.bcr/presubmit.yml b/.bcr/presubmit.yml
@@ -12,6 +12,7 @@ bcr_test_module:
         - "//base:doxygen"
         - "//latex:doxygen"
         - "//doxyfile:doxygen"
+        - "//doxylink:doxygen"
         - "//nested:doxygen"
         - "//custom:doxygen"
         - "//awesome:doxygen"
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -20,6 +20,7 @@ jobs:
             base,
             kwargs,
             doxyfile,
+            doxylink,
             latex,
             nested,
             custom,
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,4 @@
+.bazelversion
 bazel-*
 .vscode/
 MODULE.bazel.lock
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.4.1]
+
+### Added
+
+- `Doxyfile` is now included in the `doxygen` rule DefaultInfo provider
+- Mnemonic `DoxygenBuild` added to the `ctx.run` in the `doxygen` rule
+- Added support by default for the `$(OUTDIR)` make variable in the `doxygen` rule [#28](https://github.com/TendTo/rules_doxygen/pull/28) (thanks to @kaycebasques)
+- `doxylink` example in the documentation
+
+### Changed
+
+- Updated documentation
+- More information in the progress message of the `doxygen` rule
+
 ## [2.4.0]
 
 ### Changed
diff --git a/README.md b/README.md
@@ -171,6 +171,10 @@ doxygen(
 )
 ```
 
+> [!Tip]  
+> The `doxygen` rule supports [Make variables](https://bazel.build/reference/be/make-variables) substitutions.
+> By default, only `OUTDIR` and the [predefined ones](https://bazel.build/reference/be/make-variables#predefined_variables) are available, but you can add your own, as shown in the [examples](examples/substitutions).
+
 > [!Note]  
 > `srcs` and `deps` attributes are **not** interchangeable.
 > Use `srcs` with files and when you want to capture the output of another rule, and use `deps` when you want to capture the source files of other rules transitively.
diff --git a/docs/doxygen_doc.md b/docs/doxygen_doc.md
@@ -107,6 +107,35 @@ Depending on the type of the attribute, the macro will convert it to the appropr
 
 For the complete list of Doxygen configuration options, please refer to the [Doxygen documentation](https://www.doxygen.nl/manual/config.html).
 
+### Make variables
+
+There are cases where you need access to information about the build environment, such as the output directory doxygen is writing to.
+In such cases, you can use make variables in the parameters of the macro.
+The `doxygen` rule will take care of expanding them to the appropriate values.
+
+By default, the following make variables are available:
+
+- `$(OUTDIR)`: The output directory where the documentation will be generated.
+- All the predefined variables indicated in the [Bazel documentation](https://bazel.build/reference/be/make-variables#predefined_variables).
+
+The former is particularly useful when `doxygen` needs to generate unusual files, such as [tag files](https://www.doxygen.nl/manual/config.html#cfg_generate_tagfile).
+For example, you can use it to generate a tag file in the output directory:
+
+```bzl
+doxygen(
+    name = "doxygen",
+    srcs = ["README.md"] + glob(["*.h", "*.cpp"]),
+    outs = ["html", "tags"],
+    generate_tagfile = "$(OUTDIR)/tags/PolyVox.tag",
+)
+```
+
+> [!NOTE]
+> Make sure that generated files are put in some directory and that directory is included in the `outs` attribute.
+
+You can add your own substitutions by adding a rule that returns a TemplateVariableInfo provider in the `toolchains` attribute of the `doxygen` rule.
+See [this example](../examples/substitutions/) for more details.
+
 ### Differences between `srcs` and `deps`
 
 The `srcs` and `deps` attributes work differently and are not interchangeable.
diff --git a/doxygen/doxygen.bzl b/doxygen/doxygen.bzl
@@ -1,15 +1,18 @@
 """Doxygen rule for Bazel."""
 
-def _expand_make_variables(string, ctx):
+def _expand_make_variables(string, ctx, extra_sub_vars = {}):
     """Replace make variables in a string with their values.
 
     Args:
         string: The string to expand.
         ctx: The context object.
+        extra_sub_vars: A dictionary of additional variables to replace in the string.
     """
     if "$(" in string:
         for variable, value in ctx.var.items():
             string = string.replace("$(%s)" % variable, value)
+        for variable, value in extra_sub_vars.items():
+            string = string.replace("$(%s)" % variable, value)
     return string
 
 TransitiveSourcesInfo = provider(
@@ -61,7 +64,7 @@ def _doxygen_impl(ctx):
         outs.append(output_dir)
         output_group_info |= {out: depset([output_dir])}
 
-    configurations = [_expand_make_variables(conf, ctx) for conf in ctx.attr.configurations]
+    configurations = [_expand_make_variables(conf, ctx, {"OUTDIR": doxyfile.dirname}) for conf in ctx.attr.configurations]
 
     if len(outs) == 0:
         fail("At least one output folder must be specified")
@@ -83,12 +86,13 @@ def _doxygen_impl(ctx):
         inputs = ctx.files.srcs + deps + [doxyfile],
         outputs = outs,
         arguments = [doxyfile.path] + ctx.attr.doxygen_extra_args,
-        progress_message = "Running doxygen",
         executable = ctx.executable._executable,
+        mnemonic = "DoxygenBuild",
+        progress_message = "Building doxygen documentation for rule '%s'" % ctx.label.name,
     )
 
     return [
-        DefaultInfo(files = depset(outs)),
+        DefaultInfo(files = depset(outs + [doxyfile])),
         OutputGroupInfo(**output_group_info),
     ]
 
@@ -498,6 +502,35 @@ def doxygen(
 
     For the complete list of Doxygen configuration options, please refer to the [Doxygen documentation](https://www.doxygen.nl/manual/config.html).
 
+    ### Make variables
+
+    There are cases where you need access to information about the build environment, such as the output directory doxygen is writing to.
+    In such cases, you can use make variables in the parameters of the macro.
+    The `doxygen` rule will take care of expanding them to the appropriate values.
+
+    By default, the following make variables are available:
+
+    - `$(OUTDIR)`: The output directory where the documentation will be generated.
+    - All the predefined variables indicated in the [Bazel documentation](https://bazel.build/reference/be/make-variables#predefined_variables).
+
+    The former is particularly useful when `doxygen` needs to generate unusual files, such as [tag files](https://www.doxygen.nl/manual/config.html#cfg_generate_tagfile).
+    For example, you can use it to generate a tag file in the output directory:
+
+    ```bzl
+    doxygen(
+        name = "doxygen",
+        srcs = ["README.md"] + glob(["*.h", "*.cpp"]),
+        outs = ["html", "tags"],
+        generate_tagfile = "$(OUTDIR)/tags/PolyVox.tag",
+    )
+    ```
+
+    > [!NOTE]
+    > Make sure that generated files are put in some directory and that directory is included in the `outs` attribute.
+
+    You can add your own substitutions by adding a rule that returns a TemplateVariableInfo provider in the `toolchains` attribute of the `doxygen` rule.
+    See [this example](../examples/substitutions/) for more details.
+
     ### Differences between `srcs` and `deps`
 
     The `srcs` and `deps` attributes work differently and are not interchangeable.
diff --git a/examples/MODULE.bazel b/examples/MODULE.bazel
@@ -9,6 +9,15 @@ local_path_override(
 bazel_dep(name = "rules_cc", version = "0.1.1")
 bazel_dep(name = "aspect_bazel_lib", version = "2.10.0")
 bazel_dep(name = "bazel_skylib", version = "1.7.1")
+bazel_dep(name = "rules_python", version = "1.2.0")
+
+pip = use_extension("@rules_python//python/extensions:pip.bzl", "pip")
+pip.parse(
+    hub_name = "pypi",
+    python_version = "3.11",
+    requirements_lock = "//doxylink:requirements.txt",
+)
+use_repo(pip, "pypi")
 
 doxygen_extension = use_extension("@rules_doxygen//:extensions.bzl", "doxygen_extension")
 
diff --git a/examples/doxyfile/README.md b/examples/doxyfile/README.md
@@ -14,7 +14,8 @@ Keep in mind that the file will undergo the same template processing as the defa
 Namely, the following expressions will be replaced:
 
 - `# {{INPUT}}`: Subpackage directory in the sandbox.
+- `# {{DOT_PATH}}`: Indicate to doxygen the location of the `dot_executable`
 - `# {{ADDITIONAL PARAMETERS}}`: Additional parameters given in the `configurations` attribute.
 - `# {{OUTPUT DIRECTORY}}`: The directory provided in the `outs` attribute.
 
-It is highly recommended to at least use the `# {{OUTPUT DIRECTORY}}` expression at the very end of your doxyfile, since the exact path of the output is computed at runtime by Bazel and may be different on different platforms.
+It is highly recommended to at least use the `# {{OUTPUT DIRECTORY}}` expression at the very end of your Doxyfile, since the exact path of the output is computed at runtime by Bazel and it may differ on each platform.
diff --git a/examples/doxylink/BUILD.bazel b/examples/doxylink/BUILD.bazel
@@ -0,0 +1,52 @@
+load("@doxygen//:doxygen.bzl", "doxygen")
+load("@rules_python//sphinxdocs:sphinx.bzl", "sphinx_build_binary", "sphinx_docs")
+load("@rules_python//sphinxdocs:sphinx_docs_library.bzl", "sphinx_docs_library")
+load("@pypi//:requirements.bzl", "requirement")
+
+exports_files(["requirements.txt"])
+
+doxygen(
+    name = "doxygen",
+    srcs = glob([
+        "*.h",
+        "*.cpp",
+    ]),
+    outs = [
+        "html",
+        # Mark `tags` as an output folder/group, and ensure its creation
+        "tags",
+    ],
+    extract_all = True,
+    # Add the `$(OUTDIR)` make variable to specify the root output directory
+    # where to generate the file
+    generate_tagfile = "$(OUTDIR)/tags/lib.tag",
+)
+
+# Define the `sphinx` build binary that will be used to build the documentation
+sphinx_build_binary(
+    name = "sphinx_bin",
+    deps = [
+        requirement("sphinx"),
+        requirement("sphinxcontrib-doxylink"),
+    ],
+)
+
+# Capture the Doxygen output files and put them in the `doxygen` subdirectory
+sphinx_docs_library(
+    name = "sphinx_doxygen_tags",
+    srcs = [":doxygen"],
+    prefix = "doxygen/",
+)
+
+# Use sphinx to generate HTML documentation
+sphinx_docs(
+    name = "sphinx",
+    srcs = ["index.rst"],
+    config = "conf.py",
+    formats = ["html"],
+    sphinx = ":sphinx_bin",
+    # This ensures that we are in the `sphinx/_source` directory, 
+    # without more nesting
+    strip_prefix = package_name() + "/",
+    deps = [":sphinx_doxygen_tags"],
+)
diff --git a/examples/doxylink/README.md b/examples/doxylink/README.md
@@ -0,0 +1,101 @@
+# Doxyfile example
+
+A complex example combining `doxygen` and `sphinx` with the `doxylink` extension.
+This minimal example is based on the [doxylink example](https://github.com/sphinx-contrib/doxylink/tree/master/examples).
+
+```bash
+bazel build //doxyfile:doxygen
+```
+
+## Producing extra outputs
+
+`rules_doxygen` expects the `doxygen` binary to produce the `html` folder and all its contents.
+If you want to produce additional outputs, such as the `tag` files needed for the `doxylink` extension, you need to make sure they are generated in the correct location.
+You can do this by using the `OUTDIR` make variable in the `doxygen` rule:
+
+```bzl
+doxygen(
+    name = "doxygen",
+    srcs = glob([
+        "*.h",
+        "*.cpp",
+    ]),
+    outs = [
+        "html",
+        # Mark `tags` as an output folder/group, and ensure its creation
+        "tags",
+    ],
+    extract_all = True,
+    # Add the `OUTDIR` make variable to specify the root output directory
+    # where to generate the file
+    generate_tagfile = "$(OUTDIR)/tags/lib.tag",
+)
+```
+
+## Using the `doxylink` extension
+
+The `doxylink` example is slightly more involved.
+After producing the `tags` file, we want to use it with the `doxylink` extension in Sphinx.
+First of all, create a [`requirements.txt`](./requirements.txt) file listing all the necessary dependencies.
+
+Then, since we are using [rules_python](https://github.com/bazel-contrib/rules_python)'s sphinx implementation, we can just do the following:
+
+```bzl
+load("@rules_python//sphinxdocs:sphinx.bzl", "sphinx_build_binary", "sphinx_docs")
+load("@rules_python//sphinxdocs:sphinx_docs_library.bzl", "sphinx_docs_library")
+load("@pypi//:requirements.bzl", "requirement")
+
+# Define the `sphinx` build binary that will be used to build the documentation
+sphinx_build_binary(
+    name = "sphinx_bin",
+    deps = [
+        requirement("sphinx"),
+        requirement("sphinxcontrib-doxylink"),
+    ],
+)
+
+# Capture the Doxygen output files and put them in the `doxygen` subdirectory
+sphinx_docs_library(
+    name = "sphinx_doxygen_tags",
+    srcs = [":doxygen"],
+    prefix = "doxygen/",
+)
+
+# Use sphinx to generate HTML documentation
+sphinx_docs(
+    name = "sphinx",
+    srcs = ["index.rst"],
+    config = "conf.py",
+    formats = ["html"],
+    sphinx = ":sphinx_bin",
+    # This ensures that we are in the `sphinx/_source` directory,
+    # without more nesting
+    strip_prefix = package_name() + "/",
+    deps = [":sphinx_doxygen_tags"],
+)
+```
+
+Lastly, we need to ensure that the `doxylink` extension is properly configured in the Sphinx `conf.py` file.
+Here is how you can set it up:
+
+```python
+# conf.py
+
+import os
+
+# ...
+extensions = [
+                "sphinxcontrib.doxylink",
+                # other extensions ...
+            ]
+
+doxylink = {
+    "lib": (
+        os.path.abspath("doxygen/tags/lib.tag"),  # Path to the Doxygen tag file
+        "../../../html",  # Path to the Doxygen html output files. 
+        # Should be correct with respect to the hosted Sphinx documentation 
+    ),
+}
+
+# ...
+```
diff --git a/examples/doxylink/conf.py b/examples/doxylink/conf.py
@@ -0,0 +1,23 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+import os
+
+project = "rules_doxygen"
+author = "TendTo"
+copyright = "2025, TendTo"
+release = "0.0.0"
+exclude_patterns = ["**/*bazel*"]
+pygments_style = "sphinx"
+
+extensions = ["sphinxcontrib.doxylink"]
+
+doxylink = {
+    "lib": (
+        os.path.abspath("doxygen/tags/lib.tag"),  # Path to the Doxygen tag file
+        "../../../html",  # Path to the Doxygen html output files.
+        # Should be correct with respect to the hosted Sphinx documentation
+    ),
+}
+doxylink_parse_error_ignore_regexes = [r"DEFINE.*"]
+
+# master_doc = 'index'
diff --git a/examples/doxylink/index.rst b/examples/doxylink/index.rst
@@ -0,0 +1,5 @@
+:lib:`add`
+
+:lib:`doxylink_lib::Example`
+
+:lib:`doxylink_lib::Example::Example`
diff --git a/examples/doxylink/lib.cpp b/examples/doxylink/lib.cpp
@@ -0,0 +1,10 @@
+/**
+ * @file lib.cpp
+ * @author Ernesto Casablanca (casablancaernesto@gmail.com)
+ * @copyright 2024
+ * @licence Apache-2.0 license
+ */
+
+#include "lib.h"
+
+int add(int a, int b) { return a + b; }
diff --git a/examples/doxylink/lib.h b/examples/doxylink/lib.h
diff --git a/examples/doxylink/requirements.txt b/examples/doxylink/requirements.txt
