I think the comparison is looking ok. Definitely a couple of references not being handled in this branch vs main but possibly just less than ideal rather than blocking. It would be good to get them fixed though.

The tests are failing and it would be good to better understand them. I'm afraid I'm not sure what the intention of the tests are or what needs to be updated when they fail. I guess sometimes it is the code and sometimes the fixtures but I'm not sure which in this case (though likely the code, I guess.)

@michaeljones Unfortunately, I'm going to be quite busy myself for the next week or so. I'll check it out when I find some time. In the meantime, there are a few things to note:

First of all, for Doxygen 1.9.7 (I don't remember about 1.9.5 and 1.9.6, but 1.9.4 should be fine) and up, test_example[cpp_anon] will always fail. The way Doxygen handles anonymous entities changed and this has never been addressed.

Make sure you merge my latest changes. Updates to Sphinx and Doxygen broke some of the tests, so I had to make some changes.

Unfortunately, my tests are brittle. They rely on the specific output of Doxygen. Several XML attributes are ignored when doing the comparisons but otherwise the tags and non-whitespace text have to match. To accommodate multiple versions, I have a system that allows multiple versions of tests results. For example, in tests/data/examples/test_index, there is "compare.xml" and "compare-1.11.0.xml". For Doxygen versions 1.11.0 and up, "compare-1.11.0.xml" is used; otherwise, "compare.xml" is used. So far, I only made it work, up to version 1.12.0. 1.13.0 introduced a bug that affected the output (doxygen/doxygen#11541), and I had decided to wait instead of incorporating the undesired output.

Thank you for taking the time @Rouslan. I appreciate the information. I'll take another look at the tests and at the current state of the output comparison with main. I might end up adding skip/ignore to the tests but we'll see.

I think it is sensible to do a release candidate of a Breathe v5 with these changes given how much of a re-write it all is so we can give people some time to test it out and report any specific issues.

I tested this in my project with Sphinx' latest master branch and encountered an error that Rouslan already addressed in this commit

      File "/home/developer/venv/lib/python3.11/site-packages/docutils/parsers/rst/states.py", line 2156, in run_directive
        result = directive_instance.run()
                 ^^^^^^^^^^^^^^^^^^^^^^^^
      File "/home/developer/venv/lib/python3.11/site-packages/breathe/directives/function.py", line 81, in run
        args = self._parse_args(argsStr)
               ^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/home/developer/venv/lib/python3.11/site-packages/breathe/directives/function.py", line 169, in _parse_args
        paramQual = parser._parse_parameters_and_qualifiers(paramMode="function")
                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    TypeError: DefinitionParser._parse_parameters_and_qualifiers() got an unexpected keyword argument 'paramMode'

Side note: the version that pip reports after pip install git+https://github.com/breathe-doc/breathe.git@b2dc1541ffa7d15206a1ea4ae815aec3c70e52ba shows 4.36.0 instead of something like 4.35.0.dev0+b2dc154, so it can lead to confusing as to which snapshot I'm working with in my Docker container. I like using setuptools-scm to extract the version number from the Git tag and add commit data to a snapshot version.

developer@72939b2b7331:~/repo$ pip show breathe
Name: breathe
Version: 4.36.0

Thank you @JasperCraeghs - I'll investigate this and incorporate the change.

@JasperCraeghs from what I can see that fix is in main and in Rouslan's branch and still in tact in this branch. It isn't showing in the diff because it is already in main and untouched by these changes.

I think there is a chance that you have the wrong version of Breathe installed? Though I understand that I am more out of the loop than most so there is a chance I'm misunderstanding the situation.

I believe this is a link to the current state of the function.py file on this branch:

The tests are passing because I've done some minor fixes and then deleted the ones that are failing. They are failing for me locally on main and on Rouslan's branch too. I'm not sure what steps are required to get them working right now. It seems to impact the handling of index entries and references for anonymous structs and enums.

I think I would like to merge this into main and make a Breathe v5 alpha release to signal that those interested could potentially give it a shot and feedback any issues. I would welcome input from @JasperCraeghs and @Rouslan on this when they have time.

I've created #1034 with the failing tests that were deleted from here. It makes sense to try to figure out why they are failing but I'm not familiar enough with the full stack at the moment to debug them easily.

I think there is a chance that you have the wrong version of Breathe installed?

You're right. I detected no issues after installing the tool properly. I'm looking forward to a Breathe v5 alpha release. 🚀

pip install git+https://github.com/breathe-doc/breathe.git@41e05a133a1f3e9d0499a3df21ab56a6f54e9c2a --force-reinstall did not install the parser. I had to run pip install -e ../packages/breathe[build] && make -C ../packages/breathe parser, or build the wheel locally and install it that way. 🙂

I merged it but it did a squash merge (I wasn't paying attention) so I backed that out of main and redid the merge as a normal merge commit which means we preserve the history. The history is a mess but it is better to have some record of it than to have it all in one commit.

@JasperCraeghs @Rouslan - v5.0.0a2 is out with your changes when you have the time and energy to try it out. Thanks for all the work. Hopefully we'll fix up any last issues and do a full release.

Actually, I don't think the _parser.py file has been generated properly in the release. I'm going to have to look into that.

breathe v5.0.0a5 has been released and seems to have the _parser.py file. I haven't done a full build in a test project with it and it is getting late. I'll look into verifying that it works tomorrow.

breathe v5.0.0a5 from PyPI works for my project. Thank you.