search

ros2 / ros2_documentation

ROS 2 docs repository
https://docs.ros.org/en/rolling
Creative Commons Attribution 4.0 International
540 stars 1.06k forks source link

Updating docs.ros2.org documentation #3078

Open treyra opened 2 years ago

treyra commented 2 years ago

Hi, my apologies if this is the wrong place, but I was wondering if there is a process for updating API documentation at docs.ros2.org, or if that is officially supported at all anymore.

In particular, this page https://docs.ros2.org/galactic/api/sensor_msgs/msg/Imu.html (and the foxy version) has incorrect documentation (the commented out covariance fields are not commented out in the source code), and as someone new to ROS2 caused me a lot of confusion until I dug into the source.

I see that there is no page for this documentation on releases other than foxy and galactic, and that the documentation there is autogenerated, so its possible this is a depreciated resource, particularly since it's redundant with the source code. That said, the foxy version is the first result I got when searching "ros 2 sensor_msgs.msg.Imu" and is this page is the only readily available documentation online for that message (and similarly for other API documentation).

TLDR: Is there a way to make a pull request or something similar to documentation on docs.ros2.org that doesn't have an equivalent here?

danzimmerman commented 1 year ago

Related to #2309 I think, but not the same issue.

I wonder if the same short-form message docs pages for recent releases are already on a server somewhere as a workaround.

Like the Humble sensor_msgs C++ API is now hosted here (replace humble with rolling if desired): https://docs.ros.org/en/ros2_packages/humble/api/sensor_msgs/ but I don't know if the message definition pages were also generated and uploaded or not.

treyra commented 1 year ago

Related to #2309 I think, but not the same issue.

I agree it is related, in that both that issue and this one I think involve lack of clarity on how that API documentation is generated and maintained. The difference here I think is that I found an error in the documentation that caused me some confusion, but I have no idea how to submit a correction.

I wonder if the same short-form message docs pages for recent releases are already on a server somewhere as a workaround.

Like the Humble sensor_msgs C++ API is now hosted here (replace humble with rolling if desired): https://docs.ros.org/en/ros2_packages/humble/api/sensor_msgs/ but I don't know if the message definition pages were also generated and uploaded or not.

I took a look and couldn't find the message definition pages, just the variable names and other bits and pieces of documentation. It seems auto generated and incomplete.

jsduenass commented 1 year ago

Hello there docs.ros2.org API documentation is mention to be now deprecated https://docs.ros.org/en/rolling/index.html#deprecated

found this related PR #1952 were it being deprecated is introduced and #2453 where the information was move to index.rst

But I am not sure how to interpret this.

treyra commented 1 year ago

Apologies for the extremely slow reply here, I had stopped checking this issue. Thank you for the links, I agree that it is depreciated, so we could close the issue, though I think there are two issues remaining here that might be worth addressing first.

1) The current API documentation for common messages like common_interfaces/sensor_msgs/msg/Imu.msg. Is minimal / non existent. The current API documentation page (https://docs.ros.org/en/rolling/API-Docs.html) directs users to the API Docs button on the package index. For this particular example however (https://index.ros.org/p/sensor_msgs/github-ros2-common_interfaces/#rolling), the auto generated documentation (http://docs.ros.org/en/rolling/p/sensor_msgs/) is confusing and incomplete, and doesn't have any information on this message (or any other sensor message). The source code is easier to parse actually (https://github.com/ros2/common_interfaces/blob/rolling/sensor_msgs/msg/Imu.msg), and maybe we should be directing users there directly?

2) More importantly though, the first ros2 result that comes up when doing a google search for "ros2 imu msg" is https://docs.ros2.org/foxy/api/sensor_msgs/msg/Imu.html which is for a still supported version of ros2 and has incorrect information. Would it be possible to label these pages as depreciated? Since they are still the most visible API documentation to a new user, even if they are auto generated and depreciated.

I realize those might not be a big priority or are up to the user to resolve, so we can close this if it isn't a priority.