Start a draft for an Ament Python guide.

[nuclearsandwich]

This is very much a work in progress and is littered with implicit TODOs in addition to lacking much organization.

I started by trying to jot down as many major questions or known limitations of ament_python packages as I could think of.

I'm going to keep iterating on this as a draft but if anyone else would like to throw on extra info I invite anyone on the team to toss a few commits on the branch.

@sloretz do you have suggestions for exemplary ament_cmake packages containing python extensions? I have always used rclpy but I'm not sure if it has become "special" either due to the pybind11 work or by being the rcl binding for the language rather than an application package which builds python extensions.

[sloretz]

do you have suggestions for exemplary ament_cmake packages containing python extensions?

rclpy and rosbag2_py are the only two I can think of that create CPython extensions. IIUC they both use CMake instead of setuptools Extension because it's too difficult to list out include directories and link libraries without find_package(...).

I wouldn't consider rclpy or rosbag2_py special - any package that wants to pybind11 would be wise to copy their ways.

I'm not really sure what makes the ament_python build type special other than it causes colcon (colcon-ros?) to create a shell script that appends the install directory to AMENT_PREFIX_PATH.

[ct2034]

I like this pr a lot! I think documentation on ament_python is really lacking. Please let me know if I can help you somehow, @nuclearsandwich! Generally I would suggest to keep this brief for now so that there is at least something which is better than the current state. This would also streamline the review process. Then we could add additional points in follow-up prs, as needed.