Merge pull request #30 from kaycebasques/outdir

feat: support OUTDIR in Doxyfile

Author: TendTo

CHANGELOG.md

@@ -5,6 +5,12 @@ 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.2]
+
+### Added
+
+- Support for `{{OUTDIR}}` substitution in the `Doxyfile` [#30](https://github.com/TendTo/rules_doxygen/pull/30) (thanks to @kaycebasques)
+
 ## [2.4.1]
 
 ### Added

docs/doxygen_doc.md

@@ -261,7 +261,7 @@ doxygen(
 | <a id="doxygen-deps"></a>deps |  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.   |  `[]` |
 | <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_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.   |  `None` |
+| <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-outs"></a>outs |  Output folders bazel will 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"]). Note that the rule will also generate an output group for each folder in the outs list having the same name.   |  `["html"]` |
 | <a id="doxygen-doxyfile_encoding"></a>doxyfile_encoding |  This tag specifies the encoding used for all characters in the configuration file that follow.   |  `None` |

doxygen/doxygen.bzl

@@ -79,6 +79,7 @@ def _doxygen_impl(ctx):
             "# {{DOT_PATH}}": ("DOT_PATH = %s" % ctx.executable.dot_executable.dirname) if ctx.executable.dot_executable else "",
             "# {{ADDITIONAL PARAMETERS}}": "\n".join(configurations),
             "# {{OUTPUT DIRECTORY}}": "OUTPUT_DIRECTORY = %s" % doxyfile.dirname,
+            "{{OUTDIR}}": "%s" % doxyfile.dirname,
         },
     )
 
@@ -659,7 +660,9 @@ def doxygen(
             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.
+            - `# {{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.
         doxygen_extra_args: Extra arguments to pass to the doxygen executable.
         outs: Output folders bazel will 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"]).

examples/doxyfile/Doxyfile

@@ -2508,7 +2508,7 @@ TAGFILES               =
 # tag file that is based on the input files it reads. See section "Linking to
 # external documentation" for more information about the usage of tag files.
 
-GENERATE_TAGFILE       =
+GENERATE_TAGFILE       = {{OUTDIR}}/html/index.tag
 
 # If the ALLEXTERNALS tag is set to YES, all external classes and namespaces
 # will be listed in the class and namespace index. If set to NO, only the

examples/doxyfile/README.md

@@ -17,5 +17,8 @@ Namely, the following expressions will be replaced:
 - `# {{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.
+- `{{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.
 
+In this example, note how the `GENERATE_TAGFILE` value in the Doxyfile is set to `{{OUTDIR}}/html/index.tag`, which will be replaced with the actual output directory at runtime, generating the desired file.
 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.