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?
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.
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.
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 You already mentioned putting a link to that on docs.ros.org – that would be very welcome!
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.
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!
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.
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”.
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.
You already mentioned putting a link to that on 
