Create a macro for linking API classes or functions

[EmmanuelMess]

From #6181 (comment):

Instead of writing

`Node <{package_link(rclpy)}api/node.html>`__ class

everywhere to link to the API docs for Node, we need tooling that lets us write something like

{api(rclpy, rclpy.Node)} class

and expands it to the correct page.

I would also add the mapping:

`Node.get_logger() <{package_link(rclpy)}api/node.html#rclpy.node.Node.get_logger>`__

to:

{api(rclpy, rclpy.Node.get_logger)}

This isn't a priority, but I moved to an issue to keep it from falling through the cracks.

[christophebedard]

Thanks for creating this issue!

That macro thing was a simple idea. The goal is to have something that's easily maintainable, which in this case means not hardcoding api/node.html#rclpy.node.Node.get_logger, for example.

I think the solution for this will probably come in part from the tool that generates package/API documentation, rosdoc2: https://github.com/ros-infrastructure/rosdoc2. I know Doxygen is able to automatically(-ish) link to entities (e.g., classes, functions) from external documentation. It uses "tag" files, which represent entities in a given package. Perhaps we can (somehow) use that to map an entity name to a link? (However, I don't think this is working right now: ros-infrastructure/rosdoc2#91, ros-infrastructure/rosdoc2#204.) Or maybe we can use each package's genindex.html page, which lists all classes and functions along with links, e.g., https://docs.ros.org/en/rolling/p/rclcpp/genindex.html, https://docs.ros.org/en/rolling/p/rclpy/genindex.html, and https://docs.ros.org/en/rolling/p/rcl/genindex.html?

I think this will require a bit of effort. Also, we are in the process of improving our documentation, which means the structure and content will change, so I would hold off making this kind of change here for now. We could get the discussion started over on the rosdoc2 repo, though.