Document names of frontend action arguments

[christophebedard]

Feature request

This applies to both launch and launch_ros, but it is more relevant for launch_ros, since it has the main user-facing/ROS-specific launch actions.

Feature description

When using the Python launch API directly, the names of the arguments are documented in the constructor docstring. For example, see launch_ros.actions.Node.__init__(). It makes sense to expect the user to rely on that, and this can easily be part of automatically-generated API docs (e.g., using rosdoc2).

However, when using the YAML or XML frontends, the names of the arguments might differ from the underlying Python class constructor. See: #253 (comment). For example:

1. launch_ros.actions.Node.__init__() has ros_arguments:

   launch_ros/launch_ros/launch_ros/actions/node.py

   Line 128 in 13d6e1e

   ros_arguments: Optional[Iterable[SomeSubstitutionsType]] = None,

2. but the corresponding frontend argument is ros_args:

   launch_ros/launch_ros/launch_ros/actions/node.py

   Line 313 in 13d6e1e

   ros_args = entity.get_attr('ros_args', optional=True)

This is not documented anywhere. While this might be part of some examples on docs.ros.org, it should be part of some sort of documentation.

Implementation considerations

Possible solutions:

1. Change frontend argument names to be the same as the corresponding Python class constructor arguments
   • I think it's just generally accepted, so I'll leave this out
2. Add some sort of Python annotation so that the names can be automatically parsed and included in the (launch_ros) API docs
   • Probably feasible, but uncertain; would require some work
3. Manually document the frontend argument names in the top-level Python class OR Python class constructor docstring
   • Feels weird to expect users to look at the Python action class docs to find the names of the frontend arguments
4. Manually document the frontend argument names of the launch_ros actions in a document under launch_ros/doc/ and include in API docs generated by rosdoc2, similar to what launch has
   • API docs are accessible from the index.ros.org page for the launch_ros: https://docs.ros.org/en/rolling/p/launch_ros/
   • This is the simplest solution
   • However, the docs would need to be updated (manually) if anything changes, and having this documentation a bit farther away from the actual code (compared to Python docstring) makes this slightly more of a hassle
   • The argument names concern the launch frontends (launch_xml/launch_yaml), but all the logic is in the underlying Python class (launch_ros), so it wouldn't make sense to document this in the actual frontend packages. One thing to point out: while the Python action class defines the names of the arguments for the frontends, the names are the same for all frontends, and the Python action implementation has no idea that there is a YAML frontend and an XML frontend. So these are all just "names for the frontends." The user-facing document could mention "the YAML and XML frontends" to make it simpler for users, but it doesn't have to.
   • This should be linked to from one or more relevant pages in docs.ros.org:
     • https://docs.ros.org/en/rolling/How-To-Guides/Launch-file-different-formats.html
     • https://docs.ros.org/en/rolling/Tutorials/Intermediate/Launch/Launch-system.html#documentation