Issues preventing rosdoc2 from generating output (API docs)

[rkent]

Bug report

I've been investigating why launch_ros does not generate any usable python API. That is, why does a url like http://docs.ros.org/en/humble/p/launch_ros/launch_ros.actions.composable_node_container.html show nothing useful.

Required Info:

• Operating System:
  • Ubuntu 24.04
• Installation type:
  • NA, running from rosdoc2, either locally or from the official build farm.
• Version or commit hash:
  • a13359b (which is current rolling)
• DDS implementation:
  • NA
• Client library (if applicable):
  • NA

Steps to reproduce issue

View http://docs.ros.org/en/humble/p/launch_ros/launch_ros.actions.node.html

Expected behavior

Useful docs

Actual behavior

Basically empty

Additional information

There are multiple reasons why this is failing, but all related to mocking of modules in sphinx autodoc. The failure with the stock code is:

  File "/home/kent/github/rkent/launch_ros/launch_ros/launch_ros/parameters_type.py", line 50, in <module>
    SomeSubstitutionsType_types_tuple +
TypeError: unsupported operand type(s) for +: 'SomeSubstitutionsType_types_tuple' and 'tuple'
 [autodoc.import_object]

SomeSubstitutionsType_types_tuple is a mocked object, and it does not like to be added.

If you fix that (for example, surrounding it with a try block) there is a new failure. The run hangs with the displayed message:

reading sources... [  6%] launch_ros.actions

I've investigated this issue, and AFAICT it is a sphinx bug with mocked objects. There are actually two levels of this problem. Any attempt to use a mocked object as a decorator seems to generate a delay, then an error about a wrapped loop. But in node it generates an irrecoverable hang. I've developed a minimum test case to demonstrate this, and the offending code is:

@expose_action('node')
class Node():
    """Action that executes a ROS node."""

    UNSPECIFIED_NODE_NAME = '<node_name_unspecified>'

where expose_action is a sphinx mocked object. Without the line UNSPECIFIED_NODE_NAME ... you get the delay and error, but with that line you get a hang. This is reproducible running sphinx directly without rosdoc2.

I'll probably be doing a PR that manually inserts appropriate mocked objects that work correctly, but I wanted to let anyone who cares see that I am investigating.