Document names of frontend action arguments

[christophebedard]

Resolves #404

This adds boilerplate for launch_ros docs along with a page to document the argument names for the frontend actions. The setup is similar to this page in the launch docs:

• https://github.com/ros2/launch/blob/rolling/launch/doc/source/architecture.rst
• https://docs.ros.org/en/rolling/p/launch/architecture.html

Tested with rosdoc2.

[christophebedard]

This is a draft PR because this is a WIP just to get feedback on the execution/solution.

[christophebedard]

For arguments like this, it's a bit more complicated than just providing these names. What people really need are examples. I'm tempted to link to each action's frontend tests (at least for the ones that have frontend tests in test_launch_ros), like this one for the Node action: https://github.com/ros2/launch_ros/blob/38152b2d04c6b6f126d31726ac9e12888b2e2e1f/test_launch_ros/test/test_launch_ros/frontend/test_node_frontend.py. However, I'm not sure how to do it properly (i.e., how to get a distro-specific link to the source code, or maybe the test file itself can be included in the docs?), and this could get outdated + it's stereotypically "bad," so I'd just overall like to get some feedback.

[christophebedard]

Any feedback here? The more I think about it, the more I think we should just document the names of the frontend arguments in the Python class documentation. Then it just shows up in the API docs, and it's extremely close to where the argument names are defined (in the same class). It feels weird to expect users to look at the Python action class docs to find the names of the frontend arguments, but it works, and, since that's the only documentation we have, people might just look there anyway.

[fujitatomoya]

i say this is nice enhancement for user-experience, especially yaml and xml users to launch the node. and i also agree on adding examples to https://docs.ros.org/en/rolling/How-To-Guides/Launch-file-different-formats.html, this would be the 1st place for user to visit.

[clalancette]

So I agree with the sentiment that examples would also be good.

That said, I'm fine with adding in additional documentation. I especially like that this page is sort of at the "front" of the generated API documentation, so easy to find.

One thought here is how the individual actions are documented. It does seem like this is a bit of duplication of the pydoc strings that are in the class. Is it possible/would it make sense to have this "front page" documentation link to deeper into the generated API documentation? That way it will all be in sync.

[christophebedard]

Adding examples to the ROS 2 docs is a good idea.

One thought here is how the individual actions are documented. It does seem like this is a bit of duplication of the pydoc strings that are in the class. Is it possible/would it make sense to have this "front page" documentation link to deeper into the generated API documentation? That way it will all be in sync.

so I'd just list some actions on this page and link to their API doc page? The frontend argument names would have to be documented in the Python class or constructor docstring (because currently they're not documented), but yes I agree, this would keep the actual documentation in the source code itself.

[rkent]

When you say that you tested this with rosdoc2, what exactly do you mean? That is, where did you obtain rosdoc2, and how exactly did you run rosdoc2. I'd like to make recommendations on how this could work better with rosdoc2 both present and future, but that is challenging because rosdoc2 is in flux.

[christophebedard]

By "tested with rosdoc2," I meant that the two simple pages I added show up in the generated docs. I ignored the rest.

It's been a while, but:

$ pip install git+https://github.com/ros-infrastructure/rosdoc2.git@main  # Back in August 2024, probably
$ python3 -c 'import rosdoc2; print(rosdoc2.__version__)'
0.1.0
$ rosdoc2 build --package-path src/ros2/launch_ros/launch_ros/
$ google-chrome docs_output/launch_ros/index.html