Colcon Tutorial

[Yadunund]

Check the documentation for the 'Colcon Tutorial' page

Setup

• DDS vendor: FastDDS
• BuildType: Debian
• Os: Ubuntu Jammy
• Chip: Amd64

Links

• Colcon Tutorial page

Checks

• I was able to follow the documentation.
• The documentation seemed clear to me.
• The documentation didn't have any obvious errors.

---

You can find the code used to generate this test case here

[cdhabecker]

I'll take this one.

[cdhabecker]

Observations:

1. This tutorial appears to be the major colcon doc in docs.ros.org. (I searched "colcon" in the "Search docs" field, and the hits are mostly colcon command lines.) In fact, https://docs.ros.org/en/iron/Installation/Alternatives/Ubuntu-Development-Setup.html refers to this tutorial for "More info on working with a ROS workspace...".

Problems

1. "This is a brief tutorial on how to create and build a ROS 2 workspace with colcon. It is a practical tutorial and not designed to replace the core documentation." -> "core documentation" should be a link to https://colcon.readthedocs.io/.
2. "Background" section -> delete it. https://colcon.readthedocs.io/ explains the relationship to catkin and gives the github link. As for the design document mentioned in this tutorial, not even https://colcon.readthedocs.io/ mentions it. Thus, it appears to be uninteresting.
3. "Basics" section: too long, passive voice, vague. Also, this tutorial uses "--symlink-install", which counters the "out of source build" assertion in this section. Replace this entire section with: "A ROS workspace is a directory with a particular subdirectory structure. You place the source code packages in the src/ directory and colcon builds the source code into the build/, install/, and log/ directories."
4. Sections "Setup colcon_cd", "Setup colcon tab completion" and "Tips" -> delete them. The colcon documentation should be the source of truth, and if that source of truth is deficient, fix it. This tutorial should have only ROS-specific additional information, and these sections do not contain any ROS-specific information.

[cdhabecker]

Checks
Other than the problems in the preceding comment:

• I was able to follow the documentation.
• The documentation seemed clear to me.
• The documentation didn't have any obvious errors.

Tests passed
The build and test commands printed a bunch of known warnings as per colcon/colcon-core#454 (comment). Nevertheless, the tests passed.

The demo worked.

Shell output
https://gist.github.com/cdhabecker/942489fb7469bab375845de20591e79f

[Yadunund]

Thanks for testing this! Appreciate the valuable comments on improving documentation. Will continue tracking this and other suggestions to docs here #1047

I'll close this ticket as its considered completed