Add tutorial about managing multiple workspaces. (StoglRobotics#53)

* change setup-ros-workspace to create paths relative to `pwd`
* if setup-ros-workspace is executed, the new workspace is created inside the `pwd` and not in home folder anymore
* now only accept workspace name and ROS distribution as arguments

Co-authored-by: Manuel M <[email protected]>

docs/tutorials/index.rst

@@ -10,3 +10,4 @@ These tutorials will quickly get you using the ROS Team Workspace.
 
    quick-start.rst
    setting_up_rtw.rst
+   managing_multiple_workspaces.rst

docs/tutorials/managing_multiple_workspaces.rst

@@ -0,0 +1,63 @@
+=============================
+Managing multiple workspaces
+=============================
+.. _tutorial-managing-multiple-workspaces:
+
+Before learning how to manage multiple workspace with RosTeamWorkspace be sure that you have set everything up as described in this :ref:`tutorial <tutorial-setting-up-rtw>`.
+
+Also be sure that you opened a new terminal after you setup RosTeamWorkspace to be configured permanently.
+
+
+First setup a new workspace called ``ws_rolling_ros2c_demos`` inside a ``~/workspace`` folder.
+
+.. code-block:: bash
+
+   setup-ros-workspace ~/workspace/ws_rolling_ros2c_demos rolling
+
+When asked for confirmation just press <ENTER>.
+After a workspace is created open a new terminal and execute ``_ws_rolling_ros2c_demos`` alias for sourcing your new workspace. You can then switch to the new sourced workspace with ``rosd``.
+Now you can use :ref:`aliases <uc-aliases>` to interact with your workspace.
+Those can be used out of any folder you are in.
+
+Let's now add a test package into your workspace.
+
+1. Make sure your workspace is sourced by executing ``_ws_rolling_ros2c_demos``. Then enter the source folder using ``rosds`` alias.
+2. Clone ``ros2_control_demos`` repository for testing either:
+
+.. code-block:: bash
+
+   git clone [email protected]:ros-controls/ros2_control_demos.git # SSH
+   # or if no ssh key is setup:
+   git clone https://github.com/ros-controls/ros2_control_demos.git # HTTPS
+
+3. Go to the base of your workspace:
+
+.. code-block:: bash
+
+   rosd
+
+4. Install dependencies to be sure we got everything:
+
+.. code-block:: bash
+
+    rosdep install --from-paths src -y -i -r
+
+**NOTE**: if ``rosdep`` command fails with a comment that binary packages can not be found by apt, try to update you rosdep index using ``rosdep update`` command or even your package index using ``sudo apt update``.
+
+5. You can then build your workspace using:
+
+.. code-block:: bash
+
+    cb
+
+Everything should now have been built successfully!
+
+Next let's add another workspace
+
+.. code-block:: bash
+
+   setup-ros-workspace ~/workspace/ws_rolling_gz_demos rolling
+
+Now repeat the above steps to and add `gz_ros2_control <https://github.com/ros-controls/gz_ros2_control>`_ repository for testing and execute a demo from there.
+
+Now each time you open a new terminal you can use either ``_ws_rolling_ros2c_demos`` or ``_ws_rolling_gz_demos`` to source needed workspace and use the same :ref:`aliases <uc-aliases>` without constantly thinking about exact workspace/folder you are working in.

docs/tutorials/setting_up_rtw.rst

@@ -54,6 +54,7 @@ and adjust the following values using your favorite text editor:
 
 Now you are ready to:
 
-- :ref:`setup your first workspace <uc-setup-workspace>`,
 - :ref:`quick-start <tutorial-quick-start>`,
+- :ref:`setup your first workspace <uc-setup-workspace>`,
+- check how to :ref:`manage multiple workspaces <tutorial-managing-multiple-workspaces>`,
 - or check out one of the :ref:`use-cases <uc-index>`.

docs/use-cases/operating_system/create_setup_workspace.rst

@@ -8,17 +8,27 @@ This use-case describes how to setup a new ROS workspace using scripts from the
 Local workspace
 ----------------
 
-``setup-ros-workspace`` accepts ros distro name workspace suffix and workspace folder as parameters.
-All three parameters are optional.
+The ``setup-ros-workspace`` command creates a new workspace in the current folder. If you supply a path relative to your home directory, the workspace is created there.
 
 .. code-block:: bash
    :caption: Usage of the script for setting up a new ROS workspace.
    :name: setup-workspace
 
-   setup-ros-workspace ROS_DISTRO WS_FOLDER WS_PREFIX WS_SUFFIX
+   setup-ros-workspace WS_FOLDER ROS_DISTRO
+
+All parameters are optional but they are positional. If you want to omit any of the input parameters use ``"-"`` as argument.
+The script creates in ``<CURRENT_WORKING_DIRECOTRY>/<WS_FOLDER>`` a new ROS workspace with name ``<WS_FOLDER>``. However if you pass a folder name relative to your ``$HOME`` directory like for example: ``setup-ros-workspace ROS_DISTRO ~/<WS_FOLDER>``, then a new workspace is created inside ``$HOME/<WS_FOLDER>``. The passed ros distribution ``<ROS_DISTRO>`` is sourced as base if no other workspace is sourced. After the workspace has been created you have to open a new terminal and can then type the new created alias ``_<WS_FOLDER>``. This is going to source the new workspace and you can then switch to it by executing ``rosds``.
+
+Example:
+
+.. code-block:: bash
+   :caption: Example usage of the script for setting up a new ROS workspace.
+   :name: example-setup-workspace
+
+   setup-ros-workspace subfolder/my_new_workspace rolling
+
+Creates in the current folder a subfolder ``subfolder`` and then creates a new workspace called ``my_new_workspace``.  Opening a new terminal and executing ``_my_new_workspace`` is going to source this workspace.
 
-The script creates in the ``$HOME/<WS_FOLDER>`` a new ROS workspace with name ``ros_ws_<WS_PREFIX>_<ROS_DISTRO>_<WS_SUFFIX>``.
-If you want to omit any of input parameters use ``"-"`` as argument.
 Default value for ``<WS_FOLDER>`` is "workspace".
 
 .. _uc-setup-docker-workspace:
@@ -30,14 +40,14 @@ Docker workspace
    :caption: How to setup a workspace inside a docker container.
    :name: setup docker workspace
 
-   setup-ros-workspace-docker ROS_DISTRO WS_FOLDER WS_PREFIX WS_SUFFIX.
+   setup-ros-workspace-docker WS_FOLDER ROS_DISTRO
 
-Like the script ``setup-ros-workspace`` the ``setup-ros-workspace-docker`` creates a new local ROS workspace. Then a Ubuntu docker container gets built and the created workspace is mounted inside the docker container under the home directory. The first time a docker container is build can take quite a while. When the first build is finished you are directly connected as user inside the container. You can verify this by checking if your hostname has changed. To exit a container simply type the ``exit`` command.
+Like the script ``setup-ros-workspace`` the ``setup-ros-workspace-docker`` creates a new local ROS workspace. Then a Ubuntu docker container is built and the new created workspace is mounted inside the docker container under the same directory as in the host. The first time a docker container is build can take quite a while. When the first build is finished you are directly connected as user inside the container. You can verify this by checking if your hostname has changed. To exit a container simply type the ``exit`` command.
 
 Reconnect to a container
 """"""""""""""""""""""""""
 
-If you exited a container an want to reconnect as a user, you have to run the ``rtw_switch_to_docker`` command. However before executing this you have to source your workspace with ``_<workspace_alias_command>``. If you want to connect as a root user you can execute ``rtw_switch_to_docker_root``.
+If you exited a container an want to reconnect as a user, you have to run the ``rtw_switch_to_docker`` command. However before executing this you have to source your workspace with the alias  ``_<WS_FOLDER>``. If you want to connect as a root user you can execute ``rtw_switch_to_docker_root``.
 
 Recreate a container
 """"""""""""""""""""""

scripts/_RosTeamWs_Defines.bash

@@ -327,7 +327,8 @@ function user_decision {
 
 function set_framework_default_paths {
   FRAMEWORK_NAME="ros_team_workspace"
-  FRAMEWORK_BASE_PATH="$(RosTeamWS_script_own_dir)/.."
+  # readlink prints resolved symbolic links or canonical file names -> the "dir/dir_2/.." becomes "dir"
+  FRAMEWORK_BASE_PATH="$(readlink -f "$(RosTeamWS_script_own_dir)"/..)"
 
   RosTeamWS_FRAMEWORK_SCRIPTS_PATH="$FRAMEWORK_BASE_PATH/scripts"
   RosTeamWS_FRAMEWORK_OS_CONFIGURE_PATH="$RosTeamWS_FRAMEWORK_SCRIPTS_PATH/os_configure"

scripts/docker/_RosTeamWs_Docker_Defines.bash

@@ -73,7 +73,7 @@ create_docker_container() {
   fi
   local docker_host_name=$4
 
-  echo "Instantiating docker image '$docker_image_tag' and mapping workspace folder '$HOME/$ws_folder'."
+  echo "Instantiating docker image '$docker_image_tag' and mapping workspace folder to '$ws_folder'."
   echo "ros_team_ws is located under /opt/RosTeamWS/ros_ws_${RosTeamWS_DISTRO}/src/ros_team_workspace"
   xhost +local:docker
   docker run \
@@ -82,7 +82,7 @@ create_docker_container() {
   -e DISPLAY \
   --tmpfs /tmp \
   -v /tmp/.X11-unix/:/tmp/.X11-unix:rw \
-  -v "$HOME/$ws_folder":"$HOME/$ws_folder":rw \
+  -v "$ws_folder":"$ws_folder":rw \
   -v "$HOME/.ssh":"$HOME/.ssh":ro \
   --name "$docker_image_tag"-instance \
   -it "$docker_image_tag" /bin/bash

scripts/environment/setup.bash

@@ -55,7 +55,9 @@ if [[ $ros_version == 1 ]]; then
 
   WS_FOLDER_3="$HOME/$ws_folder/$ws_prefix$ros_distro$ws_suffix"
 
-  if [ -d "$WS_FOLDER_0" ]; then
+  if [ -d "$ws_folder" ]; then
+    WS_FOLDER=$ws_folder
+  elif [ -d "$WS_FOLDER_0" ]; then
     WS_FOLDER=$WS_FOLDER_0
   elif [ -d "$WS_FOLDER_1" ]; then
     WS_FOLDER=$WS_FOLDER_1
@@ -65,10 +67,6 @@ if [[ $ros_version == 1 ]]; then
     print_and_exit "Neither '$WS_FOLDER_0', '$WS_FOLDER_1', nor '$WS_FOLDER_3' exist. Can not find ROS workspace!"
   fi
 
-  if [ ! -d "$WS_FOLDER" ]; then
-    print_and_exit "'$WS_FOLDER_1' does not exist. Can not find ROS workspace!"
-  fi
-
   export ROS_WS=$WS_FOLDER
   source "$WS_FOLDER/devel/setup.bash"
 
@@ -93,7 +91,9 @@ elif [[ $ros_version == 2 ]]; then
 
   WS_FOLDER_3="$HOME/$ws_folder/$ws_prefix$ros_distro$ws_suffix"
 
-  if [ -d "$WS_FOLDER_0" ]; then
+  if [ -d "$ws_folder" ]; then
+    WS_FOLDER=$ws_folder
+  elif [ -d "$WS_FOLDER_0" ]; then
     WS_FOLDER=$WS_FOLDER_0
   elif [ -d "$WS_FOLDER_1" ]; then
     WS_FOLDER=$WS_FOLDER_1