Merge pull request #37 from renesas-abigail/feat/multi_instance
Feat: multi instance support with doxyfile_prefix
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index bf3e899..237e073 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -47,7 +47,7 @@
runs-on: ${{ matrix.os }}
steps:
- - uses: actions/checkout@v4
+ - uses: actions/checkout@v6
- name: Create .bazelversion file
working-directory: examples
run: echo "${{ matrix.bazel }}" > .bazelversion
@@ -72,7 +72,7 @@
runs-on: ${{ matrix.os }}
steps:
- - uses: actions/checkout@v4
+ - uses: actions/checkout@v6
- name: Install doxygen
uses: ssciwr/doxygen-install@v1
with:
@@ -103,7 +103,7 @@
subdir: [base]
runs-on: ${{ matrix.os }}
steps:
- - uses: actions/checkout@v4
+ - uses: actions/checkout@v6
- name: Create .bazelversion file
working-directory: examples
run: echo "${{ matrix.bazel }}" > .bazelversion
@@ -157,7 +157,7 @@
subdir: [base]
runs-on: ${{ matrix.os }}
steps:
- - uses: actions/checkout@v4
+ - uses: actions/checkout@v6
- name: Create .bazelversion file
working-directory: examples
run: echo "${{ matrix.bazel }}" > .bazelversion
@@ -225,7 +225,7 @@
runs-on: ${{ matrix.os }}
steps:
- - uses: actions/checkout@v4
+ - uses: actions/checkout@v6
- name: Create .bazelversion file
working-directory: examples
run: echo "${{ matrix.bazel }}" > .bazelversion
@@ -241,3 +241,36 @@
- name: Check doxygen version in produced index.html
run: grep "Doxygen $DEFAULT_DOXYGEN_VERSION" examples/submodules/${{ matrix.subdir }}/bazel-bin/html/index.html
shell: bash
+
+ nested:
+ strategy:
+ matrix:
+ os: [ubuntu-latest, windows-latest, macos-latest]
+ bazel: [7.0.0, 8.0.0, rolling]
+ runs-on: ${{ matrix.os }}
+
+ steps:
+ - uses: actions/checkout@v6
+ - name: Create .bazelversion file
+ working-directory: examples
+ run: echo "${{ matrix.bazel }}" > .bazelversion
+ shell: bash
+ - name: Build nested
+ run: bazel build //nested:doxygen_a //nested:doxygen_b
+ working-directory: examples/nested
+ - name: Check output (a)
+ uses: andstor/file-existence-action@v3
+ with:
+ files: examples/bazel-bin/nested/a/html/index.html
+ fail: true
+ - name: Check output (b)
+ uses: andstor/file-existence-action@v3
+ with:
+ files: examples/bazel-bin/nested/b/html/index.html
+ fail: true
+ - name: Check doxygen version in produced index.html (a)
+ run: grep "Doxygen $DEFAULT_DOXYGEN_VERSION" examples/bazel-bin/nested/a/html/index.html
+ shell: bash
+ - name: Check doxygen version in produced index.html (b)
+ run: grep "Doxygen $DEFAULT_DOXYGEN_VERSION" examples/bazel-bin/nested/b/html/index.html
+ shell: bash
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 07dc83a..0148d83 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,12 @@
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.6.1]
+
+### Added
+
+- `doxyfile_prefix` parameter to optionally allow configuring the directory into which the `Doxyfile` is emitted [#35](https://github.com/TendTo/rules_doxygen/issues/35) (thanks to @renesas-abigail)
+
## [2.6.0]
### Changed
diff --git a/docs/doxygen_doc.md b/docs/doxygen_doc.md
index 26f999d..bf1ca76 100755
--- a/docs/doxygen_doc.md
+++ b/docs/doxygen_doc.md
@@ -28,11 +28,11 @@
<pre>
load("@doxygen//:doxygen.bzl", "doxygen")
-doxygen(<a href="#doxygen-name">name</a>, <a href="#doxygen-srcs">srcs</a>, <a href="#doxygen-deps">deps</a>, <a href="#doxygen-executable">executable</a>, <a href="#doxygen-dot_executable">dot_executable</a>, <a href="#doxygen-configurations">configurations</a>, <a href="#doxygen-doxyfile_template">doxyfile_template</a>,
- <a href="#doxygen-doxygen_extra_args">doxygen_extra_args</a>, <a href="#doxygen-use_default_shell_env">use_default_shell_env</a>, <a href="#doxygen-env">env</a>, <a href="#doxygen-tools">tools</a>, <a href="#doxygen-outs">outs</a>, <a href="#doxygen-doxyfile_encoding">doxyfile_encoding</a>, <a href="#doxygen-project_name">project_name</a>,
- <a href="#doxygen-project_number">project_number</a>, <a href="#doxygen-project_brief">project_brief</a>, <a href="#doxygen-project_logo">project_logo</a>, <a href="#doxygen-project_icon">project_icon</a>, <a href="#doxygen-create_subdirs">create_subdirs</a>,
- <a href="#doxygen-create_subdirs_level">create_subdirs_level</a>, <a href="#doxygen-allow_unicode_names">allow_unicode_names</a>, <a href="#doxygen-output_language">output_language</a>, <a href="#doxygen-brief_member_desc">brief_member_desc</a>, <a href="#doxygen-repeat_brief">repeat_brief</a>,
- <a href="#doxygen-abbreviate_brief">abbreviate_brief</a>, <a href="#doxygen-always_detailed_sec">always_detailed_sec</a>, <a href="#doxygen-inline_inherited_memb">inline_inherited_memb</a>, <a href="#doxygen-full_path_names">full_path_names</a>,
+doxygen(<a href="#doxygen-name">name</a>, <a href="#doxygen-srcs">srcs</a>, <a href="#doxygen-deps">deps</a>, <a href="#doxygen-executable">executable</a>, <a href="#doxygen-dot_executable">dot_executable</a>, <a href="#doxygen-configurations">configurations</a>, <a href="#doxygen-doxyfile_prefix">doxyfile_prefix</a>,
+ <a href="#doxygen-doxyfile_template">doxyfile_template</a>, <a href="#doxygen-doxygen_extra_args">doxygen_extra_args</a>, <a href="#doxygen-use_default_shell_env">use_default_shell_env</a>, <a href="#doxygen-env">env</a>, <a href="#doxygen-tools">tools</a>, <a href="#doxygen-outs">outs</a>,
+ <a href="#doxygen-doxyfile_encoding">doxyfile_encoding</a>, <a href="#doxygen-project_name">project_name</a>, <a href="#doxygen-project_number">project_number</a>, <a href="#doxygen-project_brief">project_brief</a>, <a href="#doxygen-project_logo">project_logo</a>, <a href="#doxygen-project_icon">project_icon</a>,
+ <a href="#doxygen-create_subdirs">create_subdirs</a>, <a href="#doxygen-create_subdirs_level">create_subdirs_level</a>, <a href="#doxygen-allow_unicode_names">allow_unicode_names</a>, <a href="#doxygen-output_language">output_language</a>, <a href="#doxygen-brief_member_desc">brief_member_desc</a>,
+ <a href="#doxygen-repeat_brief">repeat_brief</a>, <a href="#doxygen-abbreviate_brief">abbreviate_brief</a>, <a href="#doxygen-always_detailed_sec">always_detailed_sec</a>, <a href="#doxygen-inline_inherited_memb">inline_inherited_memb</a>, <a href="#doxygen-full_path_names">full_path_names</a>,
<a href="#doxygen-strip_from_path">strip_from_path</a>, <a href="#doxygen-strip_from_inc_path">strip_from_inc_path</a>, <a href="#doxygen-short_names">short_names</a>, <a href="#doxygen-javadoc_autobrief">javadoc_autobrief</a>, <a href="#doxygen-javadoc_banner">javadoc_banner</a>,
<a href="#doxygen-qt_autobrief">qt_autobrief</a>, <a href="#doxygen-multiline_cpp_is_brief">multiline_cpp_is_brief</a>, <a href="#doxygen-python_docstring">python_docstring</a>, <a href="#doxygen-inherit_docs">inherit_docs</a>, <a href="#doxygen-separate_member_pages">separate_member_pages</a>,
<a href="#doxygen-tab_size">tab_size</a>, <a href="#doxygen-aliases">aliases</a>, <a href="#doxygen-optimize_output_for_c">optimize_output_for_c</a>, <a href="#doxygen-optimize_output_java">optimize_output_java</a>, <a href="#doxygen-optimize_for_fortran">optimize_for_fortran</a>,
@@ -270,6 +270,7 @@
| <a id="doxygen-executable"></a>executable | Label of the doxygen executable. | `None` |
| <a id="doxygen-dot_executable"></a>dot_executable | Label of the doxygen executable. Make sure it is also added to the `srcs` of the macro | `None` |
| <a id="doxygen-configurations"></a>configurations | List of additional configuration parameters to pass to Doxygen. | `None` |
+| <a id="doxygen-doxyfile_prefix"></a>doxyfile_prefix | Prefix to add to the Doxyfile path. | `""` |
| <a id="doxygen-doxyfile_template"></a>doxyfile_template | The template file to use to generate the Doxyfile. The following substitutions are available:<br> - `# {{INPUT}}`: Subpackage directory in the sandbox.<br> - `# {{ADDITIONAL PARAMETERS}}`: Additional parameters given in the `configurations` attribute.<br> - `# {{OUTPUT DIRECTORY}}`: The directory provided in the `outs` attribute.<br> - `{{OUTDIR}}`: The output directory where the generated documentation will be placed. Can be used anywhere in the Doxyfile, usually to generate additional output files, like tag files. | `None` |
| <a id="doxygen-doxygen_extra_args"></a>doxygen_extra_args | Extra arguments to pass to the doxygen executable. | `[]` |
| <a id="doxygen-use_default_shell_env"></a>use_default_shell_env | Whether to use the default shell environment when running doxygen. | `False` |
diff --git a/doxygen/doxygen.bzl b/doxygen/doxygen.bzl
index 060f0eb..253e7ce 100644
--- a/doxygen/doxygen.bzl
+++ b/doxygen/doxygen.bzl
@@ -55,7 +55,8 @@
)
def _doxygen_impl(ctx):
- doxyfile = ctx.actions.declare_file("Doxyfile")
+ doxyfile_prefix = ctx.attr.doxyfile_prefix
+ doxyfile = ctx.actions.declare_file("%s/Doxyfile" % doxyfile_prefix if doxyfile_prefix else "Doxyfile")
output_group_info = {}
outs = []
@@ -143,6 +144,7 @@
"deps": attr.label_list(aspects = [collect_files_aspect], doc = "List of dependencies targets whose files present in the 'src', 'hdrs' and 'data' attributes will be collected to generate the documentation. Transitive dependencies are also taken into account. Since we are only considering the source files and not the outputs, these targets **will not** be built"),
"configurations": attr.string_list(doc = "Additional configuration parameters to append to the Doxyfile. For example, to set the project name, use `PROJECT_NAME = example`."),
"outs": attr.string_list(default = ["html"], allow_empty = False, doc = """Output folders to keep. If only the html outputs is of interest, the default value will do. Otherwise, a list of folders to keep is expected (e.g. `["html", "latex"]`)."""),
+ "doxyfile_prefix" : attr.string(doc = "Prefix to add to the Doxyfile path.", default= ""),
"doxyfile_template": attr.label(
allow_single_file = True,
default = Label(":Doxyfile.template"),
@@ -207,6 +209,7 @@
executable = None,
dot_executable = None,
configurations = None,
+ doxyfile_prefix = "",
doxyfile_template = None,
doxygen_extra_args = [],
use_default_shell_env = False,
@@ -697,6 +700,7 @@
executable: Label of the doxygen executable.
dot_executable: Label of the doxygen executable. Make sure it is also added to the `srcs` of the macro
configurations: List of additional configuration parameters to pass to Doxygen.
+ doxyfile_prefix: Prefix to add to the Doxyfile path.
doxyfile_template: The template file to use to generate the Doxyfile.
The following substitutions are available:<br>
- `# {{INPUT}}`: Subpackage directory in the sandbox.<br>
@@ -1342,6 +1346,7 @@
srcs = srcs,
deps = deps,
outs = outs,
+ doxyfile_prefix = doxyfile_prefix,
configurations = configurations,
doxygen_extra_args = doxygen_extra_args,
executable = executable,
diff --git a/examples/nested/BUILD.bazel b/examples/nested/BUILD.bazel
index 0d17a54..028f11b 100644
--- a/examples/nested/BUILD.bazel
+++ b/examples/nested/BUILD.bazel
@@ -16,3 +16,32 @@
project_brief = "Example project for doxygen",
project_name = "nested",
)
+
+doxygen(
+ name = "doxygen_a",
+ srcs = ["//nested/lib_a:sources"],
+ outs = [
+ "a/html",
+ "a/tags",
+ ],
+ doxyfile_prefix = "a",
+ project_brief = "Example project for doxygen, library A",
+ project_name = "nested",
+ generate_tagfile = "$(OUTDIR)/tags/tagfile.xml",
+)
+
+doxygen(
+ name = "doxygen_b",
+ srcs = glob([
+ "lib_b/*.h",
+ "lib_b/*.cpp",
+ ]),
+ outs = [
+ "b/html",
+ "b/tags",
+ ],
+ doxyfile_prefix = "b",
+ project_brief = "Example project for doxygen, library B",
+ project_name = "nested",
+ generate_tagfile = "$(OUTDIR)/tags/tagfile.xml",
+)
diff --git a/examples/nested/README.md b/examples/nested/README.md
index 3c80a3a..4d61df6 100644
--- a/examples/nested/README.md
+++ b/examples/nested/README.md
@@ -77,3 +77,41 @@
project_name = "nested",
)
```
+
+## Handling multiple doxygen rules in the same folder
+
+Having multiple `doxygen` rules in the same folder is supported, but requires some extra configuration.
+By default, all rules would create a `Doxyfile` in the same location, causing a conflict.
+The same applies to the output `html` folder.
+To avoid this, remember to specify different `doxyfile_prefix` and `outs` for each rule:
+
+```bzl
+doxygen(
+ name = "doxygen_a",
+ srcs = ["//nested/lib_a:sources"],
+ outs = [
+ "a/html",
+ "a/tags",
+ ],
+ doxyfile_prefix = "a",
+ project_brief = "Example project for doxygen, library A",
+ project_name = "nested",
+ generate_tagfile = "$(OUTDIR)/tags/tagfile.xml",
+)
+
+doxygen(
+ name = "doxygen_b",
+ srcs = glob([
+ "lib_b/*.h",
+ "lib_b/*.cpp",
+ ]),
+ outs = [
+ "b/html",
+ "b/tags",
+ ],
+ doxyfile_prefix = "b",
+ project_brief = "Example project for doxygen, library B",
+ project_name = "nested",
+ generate_tagfile = "$(OUTDIR)/tags/tagfile.xml",
+)
+```
