Failure after Exhale: parsing Doxygen XML

[christophfroehlich]

I have made a custom rosdoc2 config for a package, which runs great on the respective rolling branch but does not on the humble branch. (the CI job uses the same workflow, i.e., OS and dependencies are the same)

Doxygen returns code "0" in both cases, I just can't find any other hint what is wrong there. Any hints what could cause the issue? Thanks in advance!

$ rosdoc2 build -p src/ros2_control/transmission_interface/
...
[~] Exhale: adding tree view css / javascript.
[+] Exhale: added tree view css / javascript.
[~] Exhale: parsing Doxygen XML.
(!) Exception caught while parsing:Traceback (most recent call last):
  File "/home/vscode/.local/lib/python3.10/site-packages/exhale/deploy.py", line 392, in explode
    textRoot.parse()
  File "/home/vscode/.local/lib/python3.10/site-packages/exhale/graph.py", line 1165, in parse
    self.parseFunctionSignatures()
  File "/home/vscode/.local/lib/python3.10/site-packages/exhale/graph.py", line 2199, in parseFunctionSignatures
    parameters.append(param.type.text)
AttributeError: 'NoneType' object has no attribute 'text'

Full log output:
humble.txt

[tfoote]

My best guess on this is that it's a version mismatch between exhale and an underlying library such as BeautifulSoup.

Tracing back
param https://github.com/svenevs/exhale/blob/c99592533143b5144a69bf685c85cdb63e534b0b/exhale/graph.py#L2199

comes from memberdef_find_all https://github.com/svenevs/exhale/blob/c99592533143b5144a69bf685c85cdb63e534b0b/exhale/graph.py#L2198

which comes from func_section.find_all https://github.com/svenevs/exhale/blob/c99592533143b5144a69bf685c85cdb63e534b0b/exhale/graph.py#L2171

which comes from cdef.find_all https://github.com/svenevs/exhale/blob/c99592533143b5144a69bf685c85cdb63e534b0b/exhale/graph.py#L2162

Which comes from parent_soup.doxygen.compounddef https://github.com/svenevs/exhale/blob/c99592533143b5144a69bf685c85cdb63e534b0b/exhale/graph.py#L2160

Which is an instance of BeautifySoup https://github.com/svenevs/exhale/blob/c99592533143b5144a69bf685c85cdb63e534b0b/exhale/graph.py#L2156

[christophfroehlich]

Thx @tfoote , I found now some time to further analyze the issue.

I realized thatrosdoc2 build -p src/ros2_control/transmission_interface/ fails from the humble branch also on my jammy and noble local devcontainers (the rolling branch succeeds). So I guess that the issue here is not a mismatch of python libraries but something empty not being catched properly.

I found out that the only single change to fix the rosdoc2 build is to add a flag in the CMakeLists.txt: add_compile_options(-Werror=conversion), -Wconversion has a different behavior.

The resulting doxygen output by
doxygen ../../../docs_build/transmission_interface/transmission_interface-public-cc-api/Doxyfile.rosdoc2
changes the files in
docs_build/transmission_interface/transmission_interface-public-cc-api/doxygen_output_Fail/xml/CMakeLists_8txt.xml and then something later in rosdoc2 fails.

Sorry, I have no idea where to start to narrow this down. But let me know how I can provide you with additional info.

[rkent]

I'm a little confused about what you are trying to accomplish here, so please forgive me if some of my comments do not make sense.

rosdoc2 is in a state of flux, frustrating for me (#144) because it must also be frustrating to developers such as yourself. Many of the unlanded PRs are hooks designed to help large projects, such as ros2_control, have better control of their documentation.

But ignoring that for a moment, if I render transmission_interface with just the PRs that are have been submitted to rosdoc2 for review and are presumably close to being landed, it looks fine as is. Using current humble branch of ros2_control, I see this: http://prrosdoc2.rosdabbler.com/humble/transmission_interface/

I have a couple of recommendations though. PR #148 has a major impact on packages, such as transmission_interface, that define conf.py but not sphinx_sourcedir. I would suggest that you:

• eliminate doc/index.rst and put that same content in a README.rst for the package but without the API links. Rely on the front page API links.
• add links to your repo and website in a package.xml url section so they appear under "Links".

If the resulting documentation page is not to your liking, the recommended way to customize this in the future is to place a modified template in your project, starting from the default https://github.com/ros-infrastructure/rosdoc2/blob/main/rosdoc2/verbs/build/builders/index.rst.jinja This is functional in the current rosdoc2, but undocumented. The documentation exists though at https://github.com/rkent/rosdoc2/tree/rkj-main/doc which hopefully someday will get landed.

I'd be happy to work with you to improve the presentation of you documentation if you desire.