| commit | 9f1475c2747706c30e4a886c012db22d85acf99c | [log] [tgz] |
|---|---|---|
| author | Ernesto Casablanca <casablancaernesto@gmail.com> | Sat Sep 07 15:14:27 2024 +0100 |
| committer | Ernesto Casablanca <casablancaernesto@gmail.com> | Sat Sep 07 15:16:29 2024 +0100 |
| tree | d2a31421beb5f5fe8c49a15488c15b4a5f207bfa | |
| parent | b0d16470b0a7e14c4c95843763eb41ee15f4d7cb [diff] |
bump: update to 1.1.3
This repository contains a Starlark implementation of Doxygen rules in Bazel.
Add the following to your MODULE.bazel:
bazel_dep(name = "rules_doxygen", version = "1.1.3", dev_dependency = True)
If you don't want to depend on the Bazel package registry or you want to use a not-yet-published version of this module, you can use an archive override by adding the following lines below the bazel_dep rule in your MODULE.bazel file:
bazel_dep(name = "rules_doxygen", version = "1.1.3", dev_dependency = True) archive_override( module_name = "rules_doxygen", urls = "https://github.com/TendTo/rules_doxygen/archive/refs/heads/main.tar.gz", strip_prefix = "rules_doxygen-main", # The SHA256 checksum of the archive file, based on the rules' version, for reproducibility # integrity = "sha256-0SCaZuAerluoDs6HXMb0Bj9FttZVieM4+Dpd9gnMM+o=", # Example )
To select a doxygen version to use, use the doxygen_extension module extension below the bazel_dep rule in your MODULE.bazel file.
doxygen_extension = use_extension("@rules_doxygen//:extensions.bzl", "doxygen_extension") use_repo(doxygen_extension, "doxygen")
By default, version 1.11.0 of Doxygen is used. To select a different version, indicate it in the version module:
doxygen_extension = use_extension("@rules_doxygen//:extensions.bzl", "doxygen_extension") # Using the 1.10.0 version of Doxygen on Windows instead of the default 1.11.0 doxygen_extension.version(version = "1.10.0", sha256 = "2135c1d5bdd6e067b3d0c40a4daac5d63d0fee1b3f4d6ef1e4f092db0d632d5b") use_repo(doxygen_extension, "doxygen")
If you don't know the SHA256 of the Doxygen binary, just leave it empty. The build will fail with an error message containing the correct SHA256.
Download from https://github.com/doxygen/doxygen/releases/download/Release_1_10_0/doxygen-1.10.0.windows.x64.bin.zip failed: class com.google.devtools.build.lib.bazel.repository.downloader.UnrecoverableHttpException Checksum was 2135c1d5bdd6e067b3d0c40a4daac5d63d0fee1b3f4d6ef1e4f092db0d632d5b but wanted 0000000000000000000000000000000000000000000000000000000000000000
[!Note] See the documentation for more information.
The main macro exposed by this module is doxygen. It generates a Doxygen documentation target from a list of sources. Only the sources are required, the rest of the parameters are optional.
# My BUILD.bazel file doxygen( name = "doxygen", # Name of the rule, can be anything srcs = glob([ # List of sources to document. "*.h", # Usually includes the source files and the markdown files. "*.cpp", ]) + ["README.md"], project_brief = "Example project for doxygen", # Brief description of the project project_name = "base", # Name of the project configurations = [ # Additional configurations to add to the Doxyfile "GENERATE_HTML = YES", # They are the same as the Doxyfile options, "GENERATE_LATEX = NO", # and will override the default values "USE_MDFILE_AS_MAINPAGE = README.md", ] tags = ["manual"] # Tags to add to the target. This way the target won't run unless explicitly called )
Use the Doxygen documentation or generate a brand new Doxyfile with doxygen -g to see all the available options to put in the configurations list. They will simply be appended at the end of the file, overriding the default values.
[!Note] See the documentation for more information or the examples directory for examples of how to use the rules.
To build the documentation, run the following command:
bazel build //path/to:doxygen_target
For example, if the BUILD.bazel file is in the root of the repository, and the target is named doxygen
# BUILD.bazel file in the root of the repository doxygen( name = "doxygen", srcs = glob([ "*.h", "*.cpp", ]), project_name = "base", )
the build command would be:
bazel build //:doxygen
The generated documentation will be in the bazel-bin/<subpackage> directory. If the BUILD.bazel file was in the root of the repository, the <subpackage> would be an empty string.
The documentation can be viewed by opening the index.html file in a browser using any web server:
# Using Python 3 cd bazel-bin/<subpackage>/html python3 -m http.server 8000
Lastly, you may want to compress the documentation to share it with others:
tar -czvf doxygen.tar.gz bazel-bin/<subpackage>/html