Plans for ROS 2 Documentation, particularly API docs?

[tfoote]

@Ingo_Lutkebohle

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.

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

@Ingo_Lutkebohle

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

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

Per-Package Documentation

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.