Documentation generation tools for ROS2

Next Generation ROS
1

I developed ROS2 package for generating documentation.


Only we have to do is write doxygen documentation in your ROS2 node.

Also, I succeed to integrate this package with github actions + github pages.
So, we can automatically deploy your documentation.
https://ouxt-polaris.github.io/color_names/#

2 Likes
2

@hakuturu583 you might want to slip a readme in there so people can figure out how to use it. :smile:

1 Like
3

Thank you for advice!
I add to the README.md to the package.

4

Hi, thank you for your contribution!
I think that this is an extremely important topic, could you provide examples of how your tool can be useful for documenting ROS 2 code (like a simple ROS 2 node snippet and the automatically generated documentation) and which features does it add over standard, non-ROS related tools?

I think that what would be extremely valuable here is to be able to automatically document the ROS 2 interfaces used by a system, i.e. which topics is a node subscribing, which topics is a node publishing to and which parameters are used by the node and can be customized by the user.

Basically a tool to automatically generate this

5

I think that this is an extremely important topic, could you provide examples of how your tool can be useful for documenting ROS 2 code (like a simple ROS 2 node snippet and the automatically generated documentation) and which features does it add over standard, non-ROS related tools?

Thanks!
This is very easy, all we have to do is just 4 thing.

  1. We write doxgen comment for the ROS2 node.
    https://github.com/OUXT-Polaris/color_names/blob/09a18f15eb027f4a80e599943fded06f227d4c18/src/color_names.cpp#L8
  2. include document_generator.cmake in CMakeLists.txt in your package.
    https://github.com/OUXT-Polaris/color_names/blob/09a18f15eb027f4a80e599943fded06f227d4c18/CMakeLists.txt#L25
  3. add_document command to the target which you want to generate documentation.
    https://github.com/OUXT-Polaris/color_names/blob/09a18f15eb027f4a80e599943fded06f227d4c18/CMakeLists.txt#L52
  4. add_package_document command to the CMakeLists.txt in you target package.
    https://github.com/OUXT-Polaris/color_names/blob/09a18f15eb027f4a80e599943fded06f227d4c18/CMakeLists.txt#L54
6

This tool was just developed yesterday, so now we can generate very poor looking documentation. :sweat:
https://ouxt-polaris.github.io/color_names/
But I think we can generate much more good looking documentation in the near future.

7

Yes, it is extreamly valuable, but I think we cannot do this fully automatically.
This is because ROS2 can decide topic names/node names in runtime.
But we have to generate documentation in build time.
So, I integrate doxygen and make it easier to write detail documentation for ROS2 users.
It is not fully automated, but we can write documentation with much less effort.

8

That’s the challenge =)

Even if names are runtime arguments, from my experience most of the times a default name is known at compile time and then it’s eventually updated using ROS remapping command line interfaces.

Parsers and static analysis tools should be able to extract information from things like

using MyMsg = std_msgs::msg::FancyMsg;
std::string my_topic_name = "fancy_topic";
auto sub = this->create_subscription<MyMsg>(my_topic_name, QoS);

In the very limited cases where a default is not provided at compile time, the fact that a subscription to FancyMsg is present could still be extracted, leaving only the name to be written by the user.

1 Like
10

Good Idea, I think doxygen contains static analystics process, so I think we can do it if we can make a ROS2 plugin for doxygen. :thinking:

11

But, unfortunately I do not know well in doxygen, so I do not know doxygen has a such kinds of feature (plugin system etc …)

12

@emersonknapp @Thomas_Moulard would this initiative be of interest for the ROS 2 tooling working group?

13

Possibly… though an initiative I think is probably more promising is building this process into the ROS 2 index - e.g. generate pages on docs.ros2.org for bloom-released packages automatically. There exists currently the “API Docs” link - I’m not sure how it works, but it’s connected for some core ros packages.

E.g. for rcl https://index.ros.org/p/rcl/ --“API Docs”–> http://docs.ros2.org/foxy/api/rcl/

Other packages don’t get this yet

E.g https://index.ros.org/p/slam_toolbox/ --“API Docs”–> 404 not found

Additionally, some packages (like slam_toolbox) above have links to the Wiki, but that only supports ROS1 packages.

Before trying to fork into an independently-maintained infrastructure via github actions, I think I’d first be more interested in seeing how we can assist Open Robotics in upgrading the ROS Index infrastructure to generate API / Wiki / Docs pages for ROS 2 packages in the index.

1 Like
14

Relevant thread: ROS 2 package documentation

1 Like
15

It seems… document generation tool is already integrated with ROS2 build farm?
I think there is no document generation tool integrated with ament_cmake.

16

I want to build documentation locally and share it my teammate easily and quickly, so I developed my tool.

17

For ROS1 there is http://wiki.ros.org/rosdoc_lite which is used by the buildfarm to generate documentation. It wraps tools like doxygen, sphinx, and epydoc.

For ROS2 I could not find out how documenation is generated. This comment seems to indicate that is still work in progress: https://answers.ros.org/question/319362/how-to-build-documentation-for-ros2-packages/

1 Like
18

Yes, it’s not done yet for ros2 - this is an up to date assessment ROS 2 package documentation

1 Like