duplicate filenames across multiple breathe projects still conflict

[jjblum]

Hello. I am using Doxygen 1.11.0, Breathe 4.35.0, and Sphinx 7.1.2 to generate docs for a large mono-repo project. I am currently constrained to using the latest versions compatible with python3.8.

We have a folder structure something like

docs/
    index.rst
    conf.py
    Doxyfile
project_1/
    docs/
        project_1_api.rst
    src/
        utils.py
project_2/
    docs/
        project_2_api.rst
    src/
        utils.py

where there is the same utils.py filename in two different locations, with different content in each file.

In the index.rst file I have the project_1_api.rst and project_2_api.rst in a toctree. An in the project_X_api.rst files I am using the .. doxygenfile:: utils.py directive.

When I had just a single breathe project (invoke Doxygen once on all the projects), I get an error along the lines of

project_1_api.rst:9: WARNING: duplicate object description of utils, other instance in project_2_api, use :noindex: for one of them

I thought that the :project: option for doxygenfile would act like a namespace, so I went to the trouble of implementing something that would call Doxygen on each individual project, changing the content in my Doxyfile via environment variables for each call. I added :project: options so that project_1_api.rst looked like

.. doxygenfile:: utils.py
   :project: project_1

and project_2_api.rst looked like

.. doxygenfile:: utils.py
   :project: project_2

And I changed breathe_projects in conf.py to have project_1 and project_2.

I am sure that the project docs are each being built and that those breathe projects can be used in the directive option successfully, but I still get an identical duplicate object warning. I tried adding a path in front of utils.py in the directive, but that did not change the result.

My expectation was that using multiple breathe projects and using the :project: option with .. doxygenfile:: would prevent such a conflict analogous to how a namespace would prevent such a conflict.

Is my expectation correct, but I have just implemented something incorrectly? Or does Breathe simply require filenames to be unique across all Breathe projects in order to safely use them with doxygenfile?

Thank you.