Streamline Python launchfiles to promote best practices

[emersonknapp]

Closes robograph-project/planning#9

The changes included in this PR are meant to produce shorter, clearer, and more flexible Python launchfiles. By showing these examples to users, we encourage them to also follow best practices for a better experience and more correct results.

Changes

• Remove all direct use of PythonLaunchDescriptionSource (and xml, yaml versions) in favor of encoding less explicit knowledge into user facing API

This makes the code shorter and therefore easier to read, and makes it easier to change out launchfile frontends.

• Make launchfiles into a declarative style, with as much included in return LaunchDescription([... as possible

This matches the XML/YAML style, and removes room for programming errors in launchfiles. I have seen plenty of cases where declared variables are then used out of order, or accidentally missed entirely. When simply declaring everything into the Action list, you can't make those mistakes.

• Replace os.path.join with PathJoinSubstitution

This allows for extension to uses with other Substitutions, such as LaunchConfiguration etc. The more flexible and correct way to write launchfiles.

• Replace get_package_share_directory with FindPackageShare

This allows the package name to be a substitution, such as from a launch arg. That's a use case I have seen. Plus the pattern allows parsing launchfiles in a context where the package prefix may not yet be known, like in build and tooling scenarios.

• Remove all direct use of TextSubstitution

It's not needed, and therefore is more confusion!

[emersonknapp]

I think the launchfile content is done, but I still need to go update the literalinclude line numbers and any surrounding exposition that might have gone stale.

[ros-discourse]

This pull request has been mentioned on ROS Discourse. There might be relevant details there:

https://discourse.ros.org/t/ros-2-pmc-meeting-minutes-for-april-29-2025/43451/1

[emersonknapp]

Updated the RST to match the new line numbers and contents, this is ready for merge IMO

[christophebedard]

Will you try to backport this?

[emersonknapp]

I will indeed try to backport it. I don't think it should be difficult. It would be nice to have included it in the Kilted tutorials testing but that's probably an unwelcome wrench in those works.