Plans for ROS 2 Documentation, particularly API docs?

Next Generation ROS
1

On docs.ros.org, I’ve read that API documentation has been deprecated with Galactic. IMO, this is a pity, because for many core packages, the API documentation is really all we got. The tutorials and concept pages are great, but they are really quite incomplete.

Personally, I would have preferred to see API documentation accessibility be improved, e.g., by also including the Python API docs for things like launch, etc.

What do others think? Am I missing something here? Is there a big plan I’m not aware of?

8 Likes
2

related to API docs discoverability issues · Issue #1354 · ros2/ros2 · GitHub ?

1 Like
3

That’s not really an accurate reading. The specific site docs.ros2.org has been deprecated. API documentation in general has not been deprecated.

Yes there is a larger plan. It was developed in 2020 and is documented here:

Since the plan was proposed we have created most of the infrastructure and content. It works similarly to how you’re used to it in ROS 1 where if you’ve added to the documentation index the ROS buildfarm will attempt to build the API documentation. (Example Rolling Doc Jobs)

All of the content from docs.ros2.org is covered there and is deprecated in favor of using the new structure. The content at docs.ros2.org was all manually maintained by individuals. Versus the new system is automated. And this was judged as necessary to scale with the community.

The building process is done by rosdoc2. There are several known issues (like python generation) that are being worked on when possible. And there is also a level that we need maintainers to help to check their documentation build results and provide the necessary metadata.

As identified by @tomoyafujita 's issue link, there are also issues of discoverability especially with respect to search engines. We want to be able to both provide backwards compatibility of urls for stability to the community, but that hinders the migration of search results to the newer site. It might make sense to consider doing a harder cutover so the newer content gets higher ranking.

All of the packages documented on index.ros.org have the link to where the “API Docs” are. For example rclcpp in the top right. This is the best way I recommend to find API docs. They’re not guarenteed to be there as per the above paragraph with some infrastructure/generation issues and secondly lack of awareness/attention from maintainers.

I think one of the big things that we should do is make sure to make index.ros.org more prominent on the docs.ros.org landing site for people to find and discover packages. It’s in the “Other ROS resources” but that belies how it is the way to find all the packages and their documentation.

6 Likes
4

After a discussion on this topic in the TSC meeting in June, I created a very first draft for a new such page at https://github.com/boschresearch/ros2_documentation/blob/proposal_for_index_page/source/Package-Index.rst. Unfortunately, I haven’t found time to do a PR yet.

My idea was to not simply link index.ros.org but provide deeper links into the huge number of packages using rosindex tags – another feature that is not know to every developer. (See https://github.com/ros-industrial/ur_msgs/blob/foxy/package.xml#L29 for an example.)

I wonder whether it is possible to come up with a list of categorial tags (e.g., motion_planning, grasping, SLAM, client_library) in advance. I looked at a couple of lists/classifications of research fields in robotics, but did not find a suitable list yet. Any ideas are very much appreciated! Alternatively, a bottom-up approach using a word cloud obtained from the tags in the package.xml files could be used, but this would be technically more complex.

2 Likes
5

Firstly, let me thank you for all the info provided! This has already helped me tremendously.

Well, not an “accurate reading” of what? Of the situation? For sure, as I now learned. But the following is a screenshot from the docs.ros.org: It puts “API documentation up to and including galactic” under a “Deprecated” header. I think you can understand how I came to the “reading” as posted above :grin: You already mentioned putting a link to that on docs.ros.org – that would be very welcome!
image

Then there are also problems such as this:
404 Not Found (ros.org)
This is the link to the API documentation of “launch_ros”, as found on its index page. As you can see, the link is broken.

1 Like
6

As someone who released their first ROS2 package not too long ago, i might add that the automated documentation generation is not mentioned in the “Releasing a Package” documentation. We were asked to create a “doc” entry in our first rosdistro PR, and stumbled over rosdoc2 after some digging (in CI job logs iirc, i’m pretty sure i haven’t seen the design doc on API documentation before reading this thread…)

So i guess the discoverability could be improved for both user and (first-time) maintainers as well!

7 Likes
7

Since this is fresh for you, could you please add some docs about things you did?

8

@destogl He already did: Releasing a ROS2 Package :: Jonas Otto

1 Like
9

Is there a recommended format for documenting the API of nodes, in particular the topic types, QoS, default topic names, publish rates, etc? Right now for DDS based API’s, we haven’t yet identified a tool. Looking through the links and examples shared here, I haven’t seen anything widely adopted by the ROS2 community.

For other protocols like MQTT or REST based API’s, we use standards like OpenAPI and AsyncAPI.

3 Likes
10

Thought I’d share it here as well. I’ve created a repository for docsets that can be used inside Zeal to look up documentation for ROS2 libraries GitHub - Serafadam/ros_docsets: Docsets to use in Dash/Zeal

1 Like
11

Are doxygen-generated pages still hosted somewhere? I followed the link from ROS Index to the sphynx output (Class Node — rclcpp 16.0.2 documentation), but personally I find the doxygen artifacts from galactic (rclcpp: rclcpp::Node Class Reference) to be much easier to consume.

1 Like
12

Neat! I wasn’t familiar with Zeal, and that seems like a really handy way to keep the docs in one place.
I always find myself just searching Google for the API docs and finding something from eloquent or foxy and going “close enough”.

2 Likes
13

@Paul_Bovbel I found a way. :slight_smile:

It’s a bit of a hassle, but if you clone the rclcpp repository and manually run doxygen, then you get the standard Doxygen theme.

It even has the inheritance diagrams:

image
image801×736 57.2 KB

For packages without a doxyfile, I did a quick test by copying (and slightly adapting) the rclcpp doxyfile and it also generated those API docs just fine.

Regards,
Johan

EDIT: i.e. manually running doxygen, as opposed to the standard way of building package documentation (rosdoc2 build) which also runs doxygen but applies the other theme to its output.

1 Like
14

Is it just a theme, or is it something about how sphinx consumes and integrates doxygen output? I keep meaning to have a poke at this because docs.ros2.org is going away, and I guess I know where to dig now (rosdoc2?)

15

It’s both, really. Sphinx only understands RST files (or Markdown files with an extension), but Doxygen doesn’t provide either of those. Additionally, we wanted the ability to integrate README.md and other hand-written documentation files into the per-package documentation. So what happens under the hood in rosdoc2 is that we invoke Doxygen to generate the XML output, and then we use a couple of Sphinx plugins (exhale and breathe) to ingest that and turn it into RST automatically. Then a Sphinx theme is applied.

16

@Paul_Bovbel

It is not a strict answer to your question, but I’d like to share my ‘best practice’ when it comes to learning ROS 2 and Gazebo Sim code.

This for sure is trivial info to those with elaborate and recent coding experience, but I think it is relevant to share nevertheless; in any case it would have saved me countless hours if I’d have known this from the start (I come from a time when state-of-the-art was C++98, Vim/Emacs and CVS/SVN instead :wink: ):


I find that generally, for ROS 2 and Gazebo, the API docs are not the best sources of info.

What I have resorted to instead, and what works really well for me, are the following three simple things:

1. Clone the source and use VSCode:
I cloned the ROS and Gazebo source tree, and I use VSCode (configured with the ROS plugin etc.) to read through the code.

This, I find, has multiple benefits, e.g.:

  • You get info tooltips when hovering above any variable or method:
    image

    This is also particularly handy when it comes to auto declared variables, as you don’t have to guess what the auto could be:
    image


  • It allows you to jump through the code by pressing ‘F12’ (or through the right mouse click menu), so you can look into some function, and then return by ‘ALT + left arrow’.

2. Look up blame history in GitHub:
To learn more about specific concepts and the ‘why’ of the code, I look up that part of code in the GitHub repository and click ‘view Git Blame’ (either the button at the top, or through clicking on the line number). This will lead you to the specific pull request (and typically also the corresponding issue) by which that part of the code was added or changed. Reading through the discussions of the issue and PR gives insight on:

  • The chosen concept,
  • Possible other options that were considered,
  • How this impacted or was impacted by other parts of the code,
  • Etc.

In some cases it even leads to elaborate design specifications (not often, though… :wink: ), or e.g. to a recording of a video conf explaning the implementation. That info typically is not disclosed anywhere else, but in the GitHub discussion.

3. Look through issues in GitHub:
In case something does not work as expected, apart from searching the Robotics Stack Exchange and the ROS/Gazebo Answers sites, cultivate the reflex to also search through the issues (open as well as closed) in the corresponding GitHub repository. Often something has been reported, discussed, possibly resolved or a workaround described, etc.


So for ROS 2 core and Gazebo Sim, this way of learning the code has proven far more valuable to me than reading header files or API docs.

1 Like