Document topics, services and actions

[vicmassy]

It would be great to document also, the topics, services and actions for each class with the default name and ros interface type

[Yadunund]

The tool is meant to document public APIs (generally from header files) based on user provided docstrings. Internally this tool calls doxygen or sphinx to generate the documentation.

Having it parse translational units or other source implementations which implement your ROS 2 node, and look for instantiations of topics, service and actions is not-trivial and also out of scope since it's not documenting public facing API. Moreover, we need this to be a capability in doxygen/sphinx.

Having said that I think you can still use this tool to document names of topics, services and actions by creating a separate header file (or class) with endpoint names defined. Then have your implementations import this header/class and replace any hardcoded strings with member variables that define the endpoints. Then, this tool will be able to document the header file with the endpoint definitions. An example of such a header can be seen in this project: https://github.com/open-rmf/rmf_ros2/blob/main/rmf_fleet_adapter/include/rmf_fleet_adapter/StandardNames.hpp

[vicmassy]

Still, as discussed in here https://discourse.ros.org/t/documentation-generation-tools-for-ros2/15511 I have a feeling that topics services and actions are part of a public API in the ROS world. Most of the ROS2 packages, need this kind of information and nowadays is made manually.

Anyway, thanks for the alternative solution.

[clalancette]

While this isn't exactly what you asked about, I think it would be good to have rosdoc2 be able to generate documentation from .msg, .srv, and .action files. This wouldn't give you the e.g. C++ API for them, but because that is all auto-generated, the pattern would be easy to document as well.

[ros-discourse]

This issue has been mentioned on ROS Discourse. There might be relevant details there:

https://discourse.ros.org/t/growing-issue-with-ros-documentation/36075/44

[rkent]

PR #76 added basic file listings for message, service, and action files which is close to what @clalancette's comments suggests.

What still needs to be done is to figure out how to allow linking to those documentations from other documentation. I've experimented with automatically generating a class link there, but I was not totally happy with the results.

In any case, I'm not really sure what more is needed to fulfill this issue. Is this asking for an automatic link from the python or c++ api of a node to the message definition?

[clalancette]

PR #76 added basic file listings for message, service, and action files which is close to what @clalancette's comments suggests.

This is a great first step.

In any case, I'm not really sure what more is needed to fulfill this issue. Is this asking for an automatic link from the python or c++ api of a node to the message definition?

I'm not entirely sure what the original reporter had in mind, but to me to complete this issue we would also need to generate documentation for the C++ and Python API used to access a class.

In other words, a message file like:

# This represents a vector in free space.

# This is semantically different than a point.
# A vector is always anchored at the origin.
# When a transform is applied to a vector, only the rotational component is applied.

float64 x
float64 y
float64 z

Also generates a C++ class, something like (very heavily edited for brevity and clarity):

template<class ContainerAllocator>
struct Vector3_
{
  using Type = Vector3_<ContainerAllocator>;

  double x;
  double y;
  double z;

  Type & set__x(
    const double & _arg)
  {
    this->x = _arg;
    return *this;
  }
  Type & set__y(
    const double & _arg)
  {
    this->y = _arg;
    return *this;
  }
  Type & set__z(
    const double & _arg)
  {
    this->z = _arg;
    return *this;
  }
};

using Vector3 =
  geometry_msgs::msg::Vector3_<std::allocator<void>>;

(it also generates an equivalent Python class)

I think we want rosdoc2 to eventually be able to document those classes, though it is unclear how to do that without first building the package. One thing we could potentially do is to have rosdoc2 directly call the rosidl pipeline (which is all written in Python) to generate these sorts of things without having to go through an entire build.

[rkent]

That's a very different class of problem than I wanted to solve. What I thought was important is, viewing the package documentation for a package that uses a particular message, I should be able to click on the message type, and it would redirect to the documentation for that message type.

You can see an example of this in my demo. From https://rosdabbler.github.io/fqdemo/fqdemo_nodes/generated/python/fqdemo_nodes.PySubPub.html you can go down to:

topic_callback(msg: fqdemo_msgs.msg.NumPwrData)

You can click on the message there, and it will go to the message documentation.

I did not include that kind of link in what was landed here, but I might suggest it later.

[clalancette]

I should be able to click on the message type, and it would redirect to the documentation for that message type.

I think that is also valuable.

[Ryanf55]

The tool is meant to document public APIs (generally from header files) based on user provided docstrings. Internally this tool calls doxygen or sphinx to generate the documentation.

Having it parse translational units or other source implementations which implement your ROS 2 node, and look for instantiations of topics, service and actions is not-trivial and also out of scope since it's not documenting public facing API. Moreover, we need this to be a capability in doxygen/sphinx.

Having said that I think you can still use this tool to document names of topics, services and actions by creating a separate header file (or class) with endpoint names defined. Then have your implementations import this header/class and replace any hardcoded strings with member variables that define the endpoints. Then, this tool will be able to document the header file with the endpoint definitions. An example of such a header can be seen in this project: https://github.com/open-rmf/rmf_ros2/blob/main/rmf_fleet_adapter/include/rmf_fleet_adapter/StandardNames.hpp

For documenting the ROS API of a node (which topics, services actions, topics, QoS), I proposed here we leverage AsyncAPI: https://discourse.ros.org/t/plans-for-ros-2-documentation-particularly-api-docs/28638/9?u=rfriedm

I also asked eProsima what their customers use to document DDS API's, and they didn't have any official tools from DDS. So far, AsyncAPI seems like the closest solution.