Link to the API in the examples

[EmmanuelMess]

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).

[christophebedard]

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

[kscottz]

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.

[EmmanuelMess]

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.

[vimal0athithan]

hello team,
can I take over resolving this issue?

[fujitatomoya]

@vimal0athithan of course you can, thanks!

[christophebedard]

We should probably get #5050 merged before this, since it adds macros to link to interface (e.g., message) docs.

[kscottz]

@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.

[christophebedard]

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