Is it possible to have multiple instances of the doxygen rule in the same package?

[renesas-abigail]

This is a great repo, thanks so much for creating it, and for the excellent examples.

I was wondering if it is possible to instantiate multiple Doxygen runs from a single BUILD file/package?

Example

# docs/doxygen/BUILD

doxygen(
    name = "main_project", 
    srcs = [
        "//src:main_project_sources",
    ]
    deps = ["//x:main_project_deps"],
    project_name = "Main Project", 
    generate_html = True,               
    generate_tagfile = "$(OUTDIR)/main/html/tagfile.xml"
    tags = ["manual"]
)

doxygen(
    name = "sub_project_1", 
    srcs = [
        "//src:project_1_sources",
    ]
    deps = ["//x:project_1_deps"],
    project_name = "Project 1", 
    generate_html = True,               
    generate_tagfile = "$(OUTDIR)/project_1/html/tagfile_project_1.xml"
    tags = ["manual"]
)

doxygen(
    name = "sub_project_2", 
    srcs = [
        "//src:project_2_sources",
    ]
    deps = ["//x:project_2_deps"],
    project_name = "Project 2", 
    generate_html = True,               
    generate_tagfile = "$(OUTDIR)/html/project_2/tagfile_project_2.xml"
    tags = ["manual"]
)

What I want is some kind of output like:

bazel-out/k8-fastbuild/docs/doxygen/main_project/html
bazel-out/k8-fastbuild/docs/doxygen/main_project/Doxyfile

bazel-out/k8-fastbuild/docs/doxygen/project_1/html
bazel-out/k8-fastbuild/docs/doxygen/project_1/Doxyfile

bazel-out/k8-fastbuild/docs/doxygen/project_2/html
bazel-out/k8-fastbuild/docs/doxygen/project_2/Doxyfile

When I try this I get errors like

ERROR: file 'docs/doxygen/Doxyfile' is generated by these conflicting actions: Label: //docs/doxygen:sub_project_1, //docs/doxygen:sub_project_2`. 

Of course it makes sense all these rules cannot generate a file called Doxyfile in the same location. But is there a way I can direct the output to subdirectories beneath the package staging area so that there is no collision?

The reason I don't just create subpackages is because in the real project, the subprojects are actually generated by another rule. So it's not easy to know pre-build what all the subprojects are.

[TendTo]

Thanks for the report. It is a scenario that, to be honest, I had not considered. The thing is, you can use the outs parameter to create some subfolders for the html files, but I suppose you can't do the same with the Doxyfile, which causes the issue.

# Partial solution. Only the html folder gets relocated, but not the Doxyfile
doxygen(
    name = "sub_project_2", 
    srcs = [
        "//src:project_2_sources",
    ],
    outs = [
        "project_2/html",
    ],
    deps = ["//x:project_2_deps"],
    project_name = "Project 2", 
    generate_html = True,
    # This would go into "bazel-out/k8-fastbuild/docs/doxygen/project_2/html/tagfile_project_2.xml"    
    generate_tagfile = "$(OUTDIR)/html/tagfile_project_2.xml" 
    tags = ["manual"]
)

What would need to change is the following code.
These days I will think of possible solutions, but feel free to suggest a fix if anything comes to mind.

# doxygen/doxygen.bzl

# ...
def _doxygen_impl(ctx):
    # Maybe we could go through the outs in the atts and see if there is any path
    # with the pattern '*/Doxyfile", and if that is the case, update the file declaration.
    # Alternatively, we could add another parameter to the rule to handle the Doxyfile path specifically.
    # The latter is probably less error prone, albeit a bit more verbose
    doxyfile = ctx.actions.declare_file("Doxyfile")

    output_group_info = {}
    outs = []
    for out in ctx.attr.outs:
        output_dir = ctx.actions.declare_directory(out)
        outs.append(output_dir)
        output_group_info |= {out: depset([output_dir])}
# ...

[renesas-abigail]

Thanks for the quick reply.

Searching the outs seems a little obscure to me. I got it to work locally using your advice about the outs parameter + adding the following:

def _doxygen_impl(ctx):
    doxyfile_prefix = ctx.attr.doxyfile_prefix
    doxyfile = ctx.actions.declare_file("{}/Doxyfile".format(doxyfile_prefix) if doxyfile_prefix else "Doxyfile")

where doxyfile_prefix is defined in _doxygen attrs as "doxyfile_prefix" : attr.string(doc = "Prefix to add to doxyfile path.", default= "").

[renesas-abigail]

Any concerns with that approach? Would it be alright if I make a PR?

[TendTo]

No, I think it's an excellent solution. I was planning to implement it myself later today, but if you have it working already I would appreciate your contribution.

[renesas-abigail]

I got it started with #37, feel free to edit.

[TendTo]

I think your pr should have fixed the issue. Try it out and, if there are not notes, I will create the new release tomorrow.

[renesas-abigail]

Thanks for cleaning it up and adding the examples! It's working perfectly for me.