Revert "revive support for the multiproject monkeypatch (#139)"

[clalancette]

This reverts commit bd5fcd7.

The monkey patching is causing a lot of problems in our usage of exhale. In particular, every single include directive is getting put into the output files multiple times, like this:

docs_build/rcl_lifecycle/rcl_lifecycle/default_sphinx_project/generated/define_visibility__control_8h_1a0767c60cb7b7851b1ff3fb00683fc13e.rst:13: WARNING: Error in "doxygendefine" directive:
invalid option data: duplicate option "project".

.. doxygendefine:: RCL_LIFECYCLE_PUBLIC_TYPE
   :project: rcl_lifecycle Doxygen Project
   :project: rcl_lifecycle Doxygen Project
   :project: rcl_lifecycle Doxygen Project
   :project: rcl_lifecycle Doxygen Project
   :project: rcl_lifecycle Doxygen Project

This PR somewhat controversially reverts the monkey-patching, getting us back to a state where things mostly work (I still have one other WARNING to chase down, but I'll do that separately). @svenevs Thoughts on this?

[florianhumblot]

@clalancette do you have a small example of a configuration which would get you this bug? I can't quite figure out what configuration would make the insert go haywire.
When reverting this commit, do your breathe directives contain a :project: member?

If you already have a :project: specifier on your breathe directives, the fix might just be to add:

if not any(":project:" in spec for spec in ret):
    ret.insert(0, ":project: " + configs._the_app.config.breathe_default_project)

instead of always inserting the :project: specifier

[svenevs]

Gah! I have company this week but still take a look this weekend.

Yeah can you please link the build setup that causes this so I have something additional to test against? I'm kind of surprised that this happens given how it works and demanding breathe_default_project implying you run exhale more than once on non monkey patched code. I'd like to fix it proper but can also get creative

[svenevs]

So I spent some time yesterday prototyping what the "right" fix should be, but my company decided to stick around so I'm not going to be able to do much about this or #147 until saturday. AFAICT the underlying problem is configs.py as a module, and it also seems not so so terrible to actually do an instance with some hacks at other places. I couldn't figure out how to build rcl_lifecycle or use the rosdoc2 thing. @clalancette Can you provide me some quick instructions (at some point this week) on how to build a project using it so I can properly test if I've eliminated that error?

@florianhumblot if I can't get a fix in soon, would you be OK with a backup plan of a dedicated monkeypatch hack branch that just gets archived in the future but rebased? They spent a lot of time helping get exhale back on its feet (as well as a lot of improvements for breathe) so I want to undo breaking them 😶

[florianhumblot]

@svenevs I don't mind per se, I can even stay on the current version for now, but it would be a lot nicer to be able to work this in correctly, since that way we can all stay on the main branch :P
If there is a clear, minimal, reproducible example I don't mind helping to add this in correctly either, but as it stands I can't really figure out how it's breaking.

[florianhumblot]

@svenevs I was able to reproduce @clalancette's issue when using rosdoc2 and building the documentation for rcl_lifecycle while on exhale's current master commit.

Steps were:

1. Install ros2-rolling
2. Install rosdoc2
3. Override the exhale version by doing pip install git+https://github.com/svenevs/exhale
4. cd'ing to the rcl_lifecycle directory
5. running rosdoc2 build --package-path ./

This would produce a bunch of errors relating to the project tag being added:

/ros-test/rcl/rcl_lifecycle/docs_build/rcl_lifecycle/rcl_lifecycle/default_sphinx_project/generated/define_visibility__control_8h_1a0767c60cb7b7851b1ff3fb00683fc13e.rst:13: ERROR: Error in "doxygendefine" directive:
invalid option data: duplicate option "project".

.. doxygendefine:: RCL_LIFECYCLE_PUBLIC_TYPE
   :project: rcl_lifecycle Doxygen Project
   :project: rcl_lifecycle Doxygen Project
   :project: rcl_lifecycle Doxygen Project
   :project: rcl_lifecycle Doxygen Project
   :project: rcl_lifecycle Doxygen Project

Inserting

if not any(":project:" in spec for spec in ret):

before inserting :project: like in the current version fixes it.

Current code, which breaks rosdoc2:

    # the monkeypatch re-configures breathe_default_project each time which was
    # foolishly relied on elsewhere and undoing that blunder requires undoing
    # all of the shenanigans that is configs.py...
    ret.insert(0, ":project: " + configs._the_app.config.breathe_default_project)
    return ret

Updated code, which does not break rosdoc2:

    # the monkeypatch re-configures breathe_default_project each time which was
    # foolishly relied on elsewhere and undoing that blunder requires undoing
    # all of the shenanigans that is configs.py...
    if not any(":project:" in spec for spec in ret):
        ret.insert(0, ":project: " + configs._the_app.config.breathe_default_project)
    return ret

I've added the "fix" to this PR: #148

@clalancette could you confirm that that addresses your concerns about the :project: bug you've been experiencing? :)

[svenevs]

Thanks for the help @florianhumblot ❤️ Pinged the other contributors on that project in #148 but I think it's good to go, and a hack on top of a hack is totally valid in this scenario 😭

Either way, I don't want to revert that commit, if things don't work then I'll do the actual fix that is needed but that may break more for them which will somewhat turn into "lets find the right way to wrap exhale" which is more effort than any of us want to put in right now.