New tutorial for ROS 2 launch files

[maryaB-osr]

Signed-off-by: maryaB-osr [email protected]

[hidmic]

First pass done!

[hidmic]

@maryaB-osr thinking this over, instead of talking about clashes we could state that there'd be no way to address each turtle separately i.e. both receive commands over the same topic, both publish pose over the same topic.

[maryaB-osr]

@hidmic So I changed the last line to this:

Both turtles in this system receive commands over the same topic and publish their pose over the same topic.
Without unique namespaces, there would be no way to distinguish between messages meant for one turtle or the other.

But now I think it's repetitive because it just seems like a long way of say of saying the previous sentence:

Unique namespaces allow the system to start two simulators without node name nor topic name conflicts.

Thoughts?

[hidmic]

@sloretz @wjwwood this is something I wanted to talk to you about.

The original roslaunch XML file would remap parent namespaces as in /input:=/turtlesim1 but that doesn't seem to work on Dashing nor Eloquent. Globbing as in /input/**:=/turtlesim1/\1 didn't work either. That's why I had to be super specific. Is that expected behavior?

[maryaB-osr]

Let me know if/when this should be updated

[wjwwood]

The original roslaunch XML file would remap parent namespaces as in /input:=/turtlesim1 but that doesn't seem to work on Dashing nor Eloquent.

Can you link that? Maybe it's a use case we overlooked, but I think our remapping in ROS 2 has to be an exact match normally (no partial matches) on a topic/service/etc... name (namespaces are not remapped as far as I know).

Globbing as in /input/**:=/turtlesim1/\1 didn't work either. That's why I had to be super specific. Is that expected behavior?

I think that should have worked, @sloretz?

[sloretz]

Whoops, missed this.

The original roslaunch XML file would remap parent namespaces as in /input:=/turtlesim1 but that doesn't seem to work on Dashing nor Eloquent.

[...] I think our remapping in ROS 2 has to be an exact match normally (no partial matches) on a topic/service/etc... name (namespaces are not remapped as far as I know).

Yeah, it has to be an exact match. That case is supposed to be covered by **, but ...

Globbing as in /input/**:=/turtlesim1/\1 didn't work either. That's why I had to be super specific. Is that expected behavior?

I think that should have worked, @sloretz?

** *, and \1 - \9 were never implemented: ros2/rcl#233 ros2/rcl#232

[clalancette]

This is the first PR I'm reviewing with actual code, instead of just commands. So I don't know what we want our convention for code examples to be. But I think that people will appreciate all of the code up-front so that they can cut-n-paste the entire example. The text that follows can then break down individual sections of code, explaining what they do. See https://clalancette.github.io/pycdlib/example-creating-new-basic-iso.html where I for an example where put this idea into practice.

Also, line numbers in the code block are useful so you can refer to specific lines of code from the text.

[maryaB-osr]

code up-front: ✔

line numbers: for some reason the linter's not been accepting the :linenos: directive for code-block. I'll try again though

[maryaB-osr]

D000 Error in "code-block" directive: unknown option: "linenos".

For some reason it works in the next tutorial when its nested under .. tabs:: > .. group-tab:: > .. code-block:: though

[wjwwood]

Not sure, make sure you're using spaces and not tabs and that you're using the right number of indented spaces?

Maybe you need to indent the following Python code a second time:

https://github.com/ros2/ros2_documentation/pull/353/files#diff-ebe5f45a06c85b302cce7f170b047089R85

The other place you use :linenos: is like that:

https://github.com/ros2/ros2_documentation/pull/353/files#diff-ebe5f45a06c85b302cce7f170b047089R118-R122

[maryaB-osr]

Maybe you need to indent the following Python code a second time:

The other place you use :linenos: is like that:

But both of those lines are throwing errors, extra indentation or not.
I tried adjusting the spaces before :linenos: (in the sphinx docs it seems like 3 spaces?) but now the linter complaints are even more bizarre

[maryaB-osr]

I think D000 warnings can come up for a few different things, right? If we suppress those for all the tutorials, won't it be possible that some actual errors will get through? Because I need line numbers on a handful, not just this one.

[wjwwood]

Yeah, I don't know what we should do, but I was just pointing out that they've been ignored in the past. Sorry I don't have time right now to investigate the technical reason for the warning right now.

[maryaB-osr]

@wjwwood That's fine, it's not necessary right now. Thanks for your input so far!

[jacobperron]

Correct, I'd added exceptions to the CI script for the tutorials under Tutorials/Actions as they make heavy use of :linenos:.

It's not the best solution, but I think it's okay if you want to add another exception for this specific tutorial file (not necessarily all of the tutorials).

[jacobperron]

@maryaB-osr I think the follow change to the .travis.yml file should do it:

-  - doc8 --ignore D001 --ignore-path build --ignore-path source/Tutorials/Actions
-  # ignore D000 in action tutorials to allow for :linenos:
-  - doc8 --ignore D000 --ignore D001 --ignore-path build source/Tutorials/Actions
+  - doc8 --ignore D001 --ignore-path build --ignore-path source/Tutorials/Actions --ignore-path source/Tutorials/LaunchFiles/CreatingLaunchFiles.rst
+  # ignore D000 in files that use :linenos:
+  - doc8 --ignore D000 --ignore D001 --ignore-path build source/Tutorials/Actions source/Tutorials/LaunchFiles/CreatingLaunchFiles.rst

[clalancette]

A couple more nits that I noticed.

[jackpien]

For those who cut-n-paste this block of code, the extra indentation needs to be removed. Causes python interpreter to complain.

[maryaB-osr]

@jackpien can you try it now?

[jackpien]

Looks great. Thanks for quick fix.

[jackpien]

Is there a design page, or specification page for launch files in general? Can we link a statement that says "if you want to learn about other launch options, configurations, go to http://xxx" to that spec page?

[maryaB-osr]

Is there a design page, or specification page for launch files in general?

@jackpien I'm going to merge this now, and hopefully have everything live by the end of the day, but will definitely find out and add it to the Related content section