Nested subpackages example

This is an example of how to use the rules in a nested subpackage that split the project in multiple libraries. Move to the parent directory and run the following command:

bazel build //nested:doxygen

Lib a

The lib_a library is in a subpackage, determined by the presence of a BUILD.bazel file. It must export a filegroup target to make the sources available to the doxygen rule.

# BUILD.bazel file in the lib_a directory
filegroup(
    name = "sources",
    srcs = glob([
        "*.h",
        "*.cpp",
    ]),
    visibility = ["//visibility:public"],
)

# BUILD.bazel file in this directory
doxygen(
    name = "doxygen",
    srcs = glob([
        "*.h",
        "*.cpp",
    ]) + ["//nested/lib_a:sources"],
    configurations = ["INPUT = nested nested/lib_a"]
    project_name = "nested",
)

Lib b

The lib_b library does not have a BUILD.bazel file, so it is not a subpackage. Its files are available to the doxygen rule from its parent directory.

# BUILD.bazel file in this directory
doxygen(
    name = "doxygen",
    srcs = glob([
        "*.h",
        "*.cpp",
        "lib_b/*.h",
        "lib_b/*.cpp",
    ]),
    configurations = ["INPUT = nested nested/lib_b"]
    project_name = "nested",
)

Putting it all together

It is possible to fuse both approaches together, with the following BUILD.bazel file:

doxygen(
    name = "doxygen",
    srcs = glob([
        "*.h",
        "*.cpp",
        "lib_b/*.h",
        "lib_b/*.cpp",
    ]) + ["//nested/lib_a:sources"],
    configurations = [
        "INPUT = nested nested/lib_a nested/lib_b",
    ],
    project_brief = "Example project for doxygen",
    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:

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",
)