ros2
Link to the API in the examples
I think APIs should be linked to in the examples in the docs.
For example in Writing a simple publisher and subscriber where it says:
The first lines of code after the comments import rclpy so its Node class can be used.
"Node" should be a link to https://docs.ros.org/en/jazzy/p/rclpy/api/node.html
create_publisher declares that the node publishes messages of type String
"String" should be a link to http://docs.ros.org/en/jazzy/p/std_msgs/interfaces/msg/String.html
And the links should be aligned with the ros version of the docs.
I believe this would help developers find and navigate the documentation and help with search engine optimization (as search engines "crawl" assigning values to linked-to sites).
That indeed sounds like a good improvement! A pull request would be appreciated 😃
And the links should be aligned with the ros version of the docs.
This is how we deal with that: https://docs.ros.org/en/rolling/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.html#macros
I don't disagree with this issue in principle, but back-filling most referenced objects with the API documentation is a pretty heavy lift. The API docs could stand significant improvement before we spend time back-filling the docs.
I don't disagree with this issue in principle, but back-filling most referenced objects with the API documentation is a pretty heavy lift. The API docs could stand significant improvement before we spend time back-filling the docs.
If you sort by most common and only do examples, I think that the amount to fix is manageable. I would also add a rule that new docs have to be linked to APIs.
We should probably get #5050 merged before this, since it adds macros to link to interface (e.g., message) docs.
@christophebedard I just sent over a second approval.
@vimal0athithan I would take a look at #5050 and understand what it is doing. Once that gets merged why don't we try a single page to test it out. Let's go slow rolling this out. Once we're a little more confident we can work on batches of a handful of files.
I just opened #5206 to link to a package's API docs (not to any specific pages in those docs). You could use those macros like this, though:
{package_link(rclpy)}api/node.html
This would expand to (for Rolling):
https://docs.ros.org/en/rolling/p/rclpy/api/node.html