Improve launch documentation #3950
Conversation
* Rework launch concepts page * Augment launch file examples Contributed by The AI Institute Signed-off-by: Michel Hidalgo <[email protected]>
There was a problem hiding this comment.
+100 for improving this. As a high-level comment: as someone with a CS background, I appreciate the terminology used to explain concepts in launch.
If I were to show this to any of my non-CS colleagues, they would probably be more confused about launch than if they hadn't read this page.
Not sure how to improve upon this though. Perhaps it should not be the only description, or be put somewhere else than Concepts/Basic?
There was a problem hiding this comment.
Thanks for the feedback! I guess we could move this modified page under Intermediate or Advanced, but I will say that I wouldn't know how to explain launch in simpler terms. One could argue that a newcomer doesn't really need to understand launch to use launch files, and that's fair, but a primer on how to run ros2 launch will only take them so far.
There was a problem hiding this comment.
I guess we could move these modified page under
IntermediateorAdvanced, but I will say that I wouldn't know how to explainlaunchin simpler terms.
I should perhaps have posted my comment on specific sections :)
As an example, the following section does actually nicely explain how things work, but is not something I would give to non-CS people:
In a way,
launchdescriptions are analogous to programs in a domain specific language tailored for process orchestration, and, in particular, ROS 2 system orchestration. When composed using the building blocks available in its native Python implementation, these descriptions resemble ASTs in procedural programming languages. The analogy has its limits, however: context is not implicitly restricted to syntactical boundaries like it would for typical variable scopes, and action execution is naturally concurrent as opposed to sequential, to name a few. However, it does bring about an important distinction that is easy to miss when writing launch files in Python: no action nor condition nor substitution carries out a computation upon instantiation but simply specifies a computation to be carried out in runtime.
There was a problem hiding this comment.
the following section does actually nicely explain how things work, but is not something I would give to non-CS people
Yeah, I get it, it presumes a CS background and then reaches out to it to make a point. I could just state it without explanation. Or we could take this to an advanced concepts page entirely.
a primer on how to run ros2 launch will only take them so far.
On a second thought, maybe we could split the difference by keeping the basic notions that are necessary to use XML launch files here, and deferring the rest along with the introduction to Python launch files. It's a detour from usual practice (Python launch files came first, Python launch files have access to all features and more), but much of the complexity that launch has to offer does not surface when using comparably simpler XML (or YAML) launch files.
There was a problem hiding this comment.
On a second thought, maybe we could split the difference by keeping the basic notions that are necessary to use XML launch files here, and deferring the rest along with the introduction to Python launch files.
personally, I would be very much in favour of this.
The current documentation seems to suggest that Python launch files are the main entry point, which I'm not sure is a desirable situation.
Similar to my comment above about explanations for users with CS backgrounds, Python launch files are considered complex and 'verbose' by many I discuss this with (surprisingly almost, as that's typically a complaint people have about XML).
Going over the XML launch files first and then gradually building up to the Python backend -- perhaps while making references to it already from the XML-focused content -- would seem like a great way to flatten the learning curve a bit.
The XML frontend would then be for "simple" launch files, while complex things like iteration, event handling, etc, would be where it would make sense for users to 'graduate' to Python launch files.
(example: showing a simple .xacro in RViz does not absolutely need a Python launch file, but composing nodes in a container with life-cycle management and other event handling definitely does at the moment)
Having written that: I'm just some guy who randomly decided to comment on your PR, so take it for what it is: a single bit of input.
There was a problem hiding this comment.
Having written that: I'm just some guy who randomly decided to comment on your PR, so take it for what it is: a single bit of input.
Haha, I know, I know. It doesn't make your arguments less valid though. I'll wait for @clalancette or @audrow to chime in.
There was a problem hiding this comment.
On a second thought, maybe we could split the difference by keeping the basic notions that are necessary to use XML launch files here, and deferring the rest along with the introduction to Python launch files. It's a detour from usual practice (Python launch files came first, Python launch files have access to all features and more), but much of the complexity that launch has to offer does not surface when using comparably simpler XML (or YAML) launch files.
What do you think about this @clalancette ?
There was a problem hiding this comment.
As @gavanderhoorn suggests, the documentation around launch could really use some improvements. So thanks for starting the conversation. I'm going to actually leave some general thoughts here, rather than doing a detailed review of what you've done here.
General thoughts
I think the biggest thing we need to think about is how to present launch to users holistically. Right now, there are ~10 places we discuss launch:
- http://design.ros2.org/articles/roslaunch.html - original design document
- https://docs.ros.org/en/rolling/p/launch/launch.html - API documentation
- https://github.com/ros2/launch - source code for
launch - https://github.com/ros2/launch/tree/rolling/launch/doc - built-in documentation for launch
- https://github.com/ros2/launch_ros/ - source code for
launch_ros - https://github.com/ros2/ros2_documentation/blob/rolling/source/Concepts/Basic/About-Launch.rst - basic introduction to the concept of launch
- https://github.com/ros2/ros2_documentation/blob/rolling/source/Tutorials/Beginner-CLI-Tools/Launching-Multiple-Nodes/Launching-Multiple-Nodes.rst - beginner introduction to running a launch file
- https://github.com/ros2/ros2_documentation/tree/rolling/source/Tutorials/Intermediate/Launch - set of intermediate tutorials on using launch and launch concepts
- https://github.com/ros2/ros2_documentation/blob/rolling/source/How-To-Guides/Launching-composable-nodes.rst - specific examples on how to launch composable nodes
- https://github.com/ros2/ros2_documentation/blob/rolling/source/How-To-Guides/Launch-file-different-formats.rst - examples on using Python, XML, and YAML launch files
There is good information in each of those places, but the overall impression I have from looking at it is that the documentation is scattered. I think it would be difficult for anyone to come along and successfully learn launch from that set of pages.
So my suggestion here is that we take a step back and figure out how we would reduce that set and make it more coherent.
Here is a straw-man argument for what the final state should be (happy to iterate on this):
- https://github.com/ros2/launch - these are the sources, so this is obviously not going anywhere
- https://github.com/ros2/launch_ros/ - ditto
- https://docs.ros.org/en/rolling/p/launch/launch.html - API documentation is still valuable as a reference, though it is not the place to learn
- https://github.com/ros2/ros2_documentation/blob/rolling/source/Concepts/Basic/About-Launch.rst - basic introduction to the concept of launch, which I think is still worthwhile introducing early (without too much detail)
- https://github.com/ros2/ros2_documentation/blob/rolling/source/Concepts/Intermediate/About-Launch-Internals.rst - more advanced introduction to launch, including the architecture and various actions, substitutions, etc.
- https://github.com/ros2/ros2_documentation/blob/rolling/source/Tutorials/Beginner-CLI-Tools/Launching-Multiple-Nodes/Launching-Multiple-Nodes.rst - beginner introduction to running a launch file (though I think we should remove the discussion of the launch file details from here)
- https://github.com/ros2/ros2_documentation/tree/rolling/source/Tutorials/Intermediate/Launch - set of intermediate tutorials on using launch
And that's it. All of the content of the pages I did not mention would be migrated to one of these places as appropriate. And we would add in lots of interlinks between the concepts, tutorials, and API documentation.
This cuts us down to ~7 places where we discuss launch, but I also think that it is far more logical this way. We have conceptual things under "Concepts", and "How to use" things under "Tutorials".
Thoughts on the overall idea, and of the specifics of what I've laid out above?
I'm a bit fuzzy on what would happen to guides. Guide != tutorial IMHO. Otherwise, the layout looks reasonable to me. I agree it doesn't help to have bits of That said, I can't stretch the scope of this PR to cover a complete overhaul. I can reorganize this contribution into basic and intermediate concepts. I can relocate the guide. |
Yes, completely agreed. Guides are meant to answer a specific question, while Tutorials walk through step-by-step, showing the user how to do something. That said, in my taxonomy above there are only two guides:
I think both of those could be reasonably incorporated into Tutorials and removed from the Guides. Though again, I'm willing to hear other opinions and change it up.
This is a hard one to gauge for me. The ability to have detailed documentation in the individual packages is definitely a feature. But I also think that we've been most successful (in terms of people finding it) with documentation that is here in
Yeah, that's totally fair. I think it is worthwhile for us to figure out what we want the final product to look like, and write it down somewhere (likely an issue in this repository). Then as people have time to work on it, at least we have a framework to fit it into. |
I see. That's fair.
I had something like this in mind for a
IMHO this is too detailed to be hosted in https://docs.ros.org. For the front page, the
Sounds reasonable. I can adapt this PR to cover concepts and a tutorial on writing launch files. |
|
@clalancette friendly ping |
|
@clalancette another friendly ping (now that ROSCON is over :)) |
|
@mhidalgo-bdai So sorry for the very delayed response. I'm finally coming back around to this. I like the topics covered in your table of contents. That is exactly the type of thing I think we should cover. What I'm wondering is whether it is worthwhile to split it up, though. In particular, I'm kind of thinking we can take your Concepts section and move it into Concepts/Intermediate here on https://docs.ros.org . And then we can take the User Guide portion and move it into Tutorials/Intermediate here on https://docs.ros.org. That would leave only "Architecture" and "API" reference in the individual packages, where I think they belong. Incorporating that idea back into what I mentioned before, we would end up with something like this:
Thoughts on that? |
|
This looks reasonable. I can try to rework this patch into both concepts and user guide pages. It may take me a while though (internal re-prioritization). I'll ping you when I get to circle back. |
| All of the above is specified in a launch file, which can be written in Python, XML, or YAML. | ||
| This launch file can then be run using the ``ros2 launch`` command, and all of the nodes specified will be run. | ||
| ``launch`` provides the means to orchestrate the execution of ROS 2 systems, in ROS 2 terms. | ||
| _Launch files_ describe the orchestration procedure, including but not limited to which nodes to run, how to run them, and which arguments to use for them. |
There was a problem hiding this comment.
just a comment, this does not block the PR.
i would expect by orchestrated that auto-healing like restarting the node on different physical host system if anything happens, replication of nodes and so on. AFAIK, those orchestration features are not supported ROS 2 launch?
including but not limited to which nodes to run, how to run them, and which arguments to use for them.
IMO, those are just configuration and setting for the ROS 2 node?
| Moving parts | ||
| ------------ | ||
|
|
||
| ``launch`` works with [_actions_](https://docs.ros.org/en/rolling/p/launch/launch.html#launch.Action), abstract representations of computational procedures with side effects on its execution environment. |
There was a problem hiding this comment.
the same fix can be applied to other places as well.
| ``launch`` works with [_actions_](https://docs.ros.org/en/rolling/p/launch/launch.html#launch.Action), abstract representations of computational procedures with side effects on its execution environment. | |
| ``launch`` works with [_actions_](https://docs.ros.org/en/{DISTRO}/p/launch/launch.html#launch.Action), abstract representations of computational procedures with side effects on its execution environment. |
This patch improves upon existing documentation on
launchto make it easier on newcomers to use it. In particular, it:About Launchpage underConceptsto be a bit more thorough, andUsing Python, XML, and YAML for ROS 2 Launch fileswith more examples.Contributed by The AI Institute.