New tutorial for creating a workspace

[maryaB-osr]

Signed-off-by: maryaB-osr marya@openrobotics.org

[dirk-thomas]

We wanted to make sure to embed the distro name into the directory for macOS / Windows too, right?

[maryaB-osr]

Does this do it #380 ?

[dirk-thomas]

If the user has already sourced the underlay they only need to source the local_setup file of the overlay.

Or they just source the setup file of the overlay which implicitly will source the underlay.

[clalancette]

Actually, an explanation of the difference between setup.bash and local_setup.bash would probably be good here. It's a question I get a lot.

[maryaB-osr]

Adding this note:

.. note::

  Sourcing the ``local_setup`` of the overlay will only add the packages available in the overlay to your environment.
  ``setup`` sources the overlay as well as the underlay it was created in, allowing you to utilize both workspaces.

  So, sourcing your main ROS 2 installation's ``setup`` and then the ``dev_ws`` overlay's ``local_setup``, like you just did,
  is the same as just sourcing ``dev_ws``'s ``setup``, because that includes the environment of the underlay it was created in.

Does that make sense?

[clalancette]

Do we have a tutorial that talks about rosdep? Otherwise, this is kind of magical. If we do have a tutorial talking about rosdep, we should probably have some language saying that you'll learn about it later.

[maryaB-osr]

Hmm.. there is a bit more about dependencies once they start creating their own packages, but not much more about rosdep specifically. I'll say "later" for now and make a note to add more in-depth notes about rosdep. I also think the opening and closing lines of this section provide a sufficient temporary introduction, albeit very vague

[clalancette]

I'm fine with punting on rosdep for now. I've opened #381 to track adding a tutorial about rosdep.

[clalancette]

Actually, an explanation of the difference between setup.bash and local_setup.bash would probably be good here. It's a question I get a lot.

[tfoote]

I had a few more suggestions but otherwise it looks good to me.

For quick reference the tutorial can be reviewed at: https://ros2-documentation-pr-359.herokuapp.com/Tutorials/Workspace/CreatingAWorkspace.html

[clalancette]

I've got a few more nits to fix.

[clalancette]

This looks good to me, but you'll want to fix the failing CI before merging.