I finished the merge.

I understand now what the purpose for breaking up the pull request would be. It's certainly possible, but it would take a while. I would have go through all my commits, one by one, and either selectively undo certain changes, or conversely, create a new branch and selectively apply certain changes. I would need to go through all the commits multiple times and reapply the changes for the subsequent pull requests. By the time I'm done, there would probably be new changes in the original repository, and translating new changes from the old code into the new code is also not fun. Either way, the first pull request would still be the biggest because the parser's data types permeate so much of the code. There was even code in the original parser that had to be moved outside the parser because it was specific to a much later step in Breathe's operation.

I'm not enthusiastic about doing that. I would have to be convinced that smaller pull requests are worth the effort.

Also, in case the tone of this text comes off as negative: I wish to clarify that I didn't mind being asked.

The build log contains the following warning twice when I build my project documentation with this PR (I use Doxygen 1.12.0):

/home/developer/venv/lib/python3.11/site-packages/breathe/_parser.py:2274: ParseWarning: Warning on line 65: unexpected element "simplesect"
  warnings.warn(ParseWarning(f'Warning on line {self.parser.CurrentLineNumber}: {msg}'))

@Rouslan - to clarify, your work still depends on the C parser code in this branch? I had the vaguest idea that you'd tried that route and then didn't need the C code in the end but maybe I was wrong.

@michaeljones No, the C version is no longer generated. I didn't delete the template for the C version right away and I ended up forgetting about it until now. It can be safely removed.

@Rouslan - Ok, good to know. Thank you for the quick response. I'll delete the xml_parser_generator folder and anything that touches it? I guess?

@michaeljones Oh, you can't delete the whole folder, only "module_template.c.in". The Python version of the parser is also generated.

@JasperCraeghs I have updated the parser and there shouldn't be any more parse warnings (at least until a new version of Doxygen comes out). Please let me know if any show up.

What is the best practice for from __future__ import annotations these days? We seem to have it in a lot of files by not all? Should it be in all? Or just the top level entry point files? Or any file that uses annotations of some kind?

And for type checking, do we want the:

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from sphinx.application import Sphinx

pattern everywhere that we use it? When does that last non-type-aware python version end-of-life? Looks like 3.9 will EOL by the end of this year.

I don't know what the best practice is, but I have been adding from __future__ import annotations as needed. This import changes Python's behavior so that annotations are not evaluated until they are needed. This means they can refer to classes defined later in the file, without needing to use string literals. This also means mutually recursive imports are not an issue for type checking because the names in annotations are not looked up until after all the modules are scanned.

This is also why if TYPE_CHECKING: is used. This is not for compatibility with multiple Python versions. TYPE_CHECKING is only true when Mypy or some other type checker is reading the code. Some modules are only imported because their types are used in annotations. By only importing when TYPE_CHECKING is true, the modules are only loaded when checking types, not when running code normally.