wrapping of exhale is not valid

[svenevs]

Setting breathe_default_project has been a hard requirement for exhale since its inception since it was only designed with consideration of single-project builds. This is a core design flaw, but at it's root in the absence of breathe_default_project you must specify :project: <some key in breathe_projects> to a given .. doxygen*:: directive, and in all honesty I didn't know how to deal with it.

rosdoc2/rosdoc2/verbs/build/builders/sphinx_builder.py

Lines 64 to 66 in 40a07e0

	# Enable Breathe and arbitrarily select the first project.
	extensions.append('breathe')
	breathe_default_project = next(iter(breathe_projects.keys()))

I've tested against rcl_lifecycle but it seems likely that it's only working as a fluke.

svenevs/exhale#148 prevents the wrapping byproduct but I'm not confident it is a full resolution -- since right now next(iter(breathe_projects.keys())) may result in the wrong entry. That said, I think the issue is (hopefully) better solved here.

1. Probably the correct solution is to actually configure breathe_default_project correctly in your wrapper, rather than set an arbitrary value.
2. If you make your custom specifications mapping include :project: the right thing, this would also bypass this as an underhanded implementation detail of that PR.
3. If more than one breathe_project is going to get executed in a single run of sphinx-build, then this is where things get tricky.

Right now there's some band-aids for multiproject support that are currently functional via a monkeypatch hack which was only recently revived (and consequently broke rosdoc2). svenevs/exhale#27

If you are building more than one breathe project in a single execution of sphinx-build, you may be best off vendoring the monkeypatch. The underlying problem is that (again, core design flaw), exhale.configs is a module. It is unclear to me if you need to support multiple breathe projects, if you do right now all I can do is make the monkeypatch work again and suggest subscribing to 27 over there since resolving it will include additional breaking changes.

[rkent]

I'm trying to understand this issue, and what if anything it would take to resolve it.

If I might reword, the issue is that rosdoc2 sort of implies that multi project support exists, but only takes the first project. But AFAICT there is no multi-project support in rosdoc2. breathe_default_project = next(iter(breathe_projects.keys())) may be an odd way to get the one project, but it does seem to work.

I don't think there is any action required here.