CLI is not experimental but primary approach.

destogl · destogl · commit 2b80753cb19d · 2025-02-09T16:20:53.000+01:00
Update tutorial on managing workspaces using RTW CLI.
diff --git a/docs/docker/index.rst b/docs/docker/index.rst
@@ -3,7 +3,7 @@ Docker
 ===========
 .. _docker-overview:
 
-RosTeamWS supports the usage of docker containers.
+RTW supports the usage of docker containers.
 
 .. toctree::
    :maxdepth: 1
diff --git a/docs/guidelines/index.rst b/docs/guidelines/index.rst
@@ -2,7 +2,7 @@
 Guidelines
 ===========
 
-RosTeamWS proposes development and architecture guidelines to boost efficiency and activate synergy effects inside a development team and between the teams.
+RTW proposes development and architecture guidelines to boost efficiency and activate synergy effects inside a development team and between the teams.
 
 .. toctree::
    :maxdepth: 1
diff --git a/docs/index.rst b/docs/index.rst
@@ -2,7 +2,7 @@
 Welcome the documentation of *ROS Team Workspace*-Framework
 ============================================================
 
-ROS Team Workspace (RosTeamWS) is a framework for boosting collaboration in teams when developing software for robots using `Robot Operating System (ROS) <https://www.ros.org/>`_.
+ROS Team Workspace (RTW) is a framework for boosting collaboration in teams when developing software for robots using `Robot Operating System (ROS) <https://www.ros.org/>`_.
 It supports both **ROS** and **ROS 2**.
 Its main goal is to optimize the workflow of development teams and focus more on programming robots.
 
@@ -14,8 +14,8 @@ From 2021, the framework is maintained by Stogl Robotics Consulting.
 ..    :depth: 2
 
 
-Purpose of the *RosTeamWS*
-==========================
+Purpose of the *RosTeamWorkspace (RTW)*
+========================================
 
 This package targets the following stakeholders:
 
@@ -33,7 +33,7 @@ The framework is the main entry-point for teams to:
 #. provide scripts for easy use of ROS.
 
 
-To achieve this, RosTeamWS defines:
+To achieve this, RTW defines:
 
 #. an architecture of overlaid workspaces for sharing standard ROS packages;
 #. standardized package structure for straightforward collaboration;
@@ -43,16 +43,16 @@ To achieve this, RosTeamWS defines:
 
 DISCLAIMER
 ==========
-The work in the RosTeamWS-framework tries to follow, if applicable, `ROS Enhancement Proposals (REPs) <https://www.ros.org/reps/rep-0000.html>`_. Still, collisions in the best-practices proposals may occur.
+The work in the RTW-framework tries to follow, if applicable, `ROS Enhancement Proposals (REPs) <https://www.ros.org/reps/rep-0000.html>`_. Still, collisions in the best-practices proposals may occur.
 The opinions and proposals stated here are merely related to the authors' experiences.
 
 
 .. toctree::
    :hidden:
 
    tutorials/index.rst
+   rtwcli/index.rst
    guidelines/index.rst
    use-cases/index.rst
    docker/index.rst
-   rtwcli/index.rst
    faq/index.rst
diff --git a/docs/rtwcli/index.rst b/docs/rtwcli/index.rst
@@ -1,17 +1,12 @@
-==============================
-RosTeamWS CLI (Experimental)
-==============================
+==============
+RTW CLI
+==============
 
-RosTeamWS has a command line interface (CLI) that provides a set of commands to
+RTW has a command line interface (CLI) that provides a set of commands to
 manage ROS workspaces incl. Docker workspaces. The CLI is designed to have a
 more user-friendly overview of the available RTW commands and to provide a more
 intuitive way to interact with RTW.
 
-.. warning::
-   The CLI is still in the experimental stage and may have bugs or issues.
-   Please report any bugs or issues to the RosTeamWS GitHub repository.
-
-
 How to install the CLI
 """"""""""""""""""""""""
 .. _rtwcli-setup:
diff --git a/docs/tutorials/managing_multiple_workspaces.rst b/docs/tutorials/managing_multiple_workspaces.rst
@@ -3,63 +3,65 @@ 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 the :ref:`setting up RosTeamWorkspace tutorial <tutorial-setting-up-rtw>`.
+Before learning how to manage multiple workspace with RTW be sure that you have set everything up as described in the :ref:`setting up RTW tutorial <tutorial-setting-up-rtw>`.
 
-Also be sure that you opened a new terminal after you setup RosTeamWorkspace to be configured permanently.
+Also be sure that you have opened a new terminal after you RTW setup to be configured permanently.
 
 
-First setup a new workspace called ``ws_rolling_ros2c_demos`` inside a ``~/workspace`` folder.
+Lets setup a new workspace called ``ws_rolling_ros2_control_demos`` inside a ``~/workspace`` folder.
 
 .. code-block:: bash
 
-   setup-ros-workspace ~/workspace/ws_rolling_ros2c_demos rolling
+   rtw workspace create \
+      --ws-folder ~/workspace/ws_rolling_ros2c_demos \
+      --ros-distro 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.
+After a workspace is created, open a new terminal and execute ``rtw ws ws_rolling_ros2c_demos`` command for sourcing your newly created workspace.
+Now you can start using *RTW* aliases, for example directly switch to the root folder of your workspace using ``rosd``.
+Check other aliases for interaction with the workspace :ref:`here <uc-aliases>`.
 Those can be used out of any folder you are in.
 
-Let's now add a test package into your workspace.
+Let's now add a package to 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:
+1. Make sure your workspace is sourced by executing ``rtw ws ws_rolling_ros2c_demos``.
+   Then enter the source folder using ``rosds`` alias.
+
+2. Lets clone ``ros2_control_demos`` repository for testing using:
 
 .. code-block:: bash
 
    git clone git@github.com: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:
+3. Now install dependencies using *RTW* :ref:`alias <uc-aliases-dependencies>`:
 
 .. code-block:: bash
 
-    rosdep install --from-paths src -y -i -r
+   rosdepi  # Alias for: rosdep install -y -i -r --from-paths \$ROS_WS/src
 
 .. note:: if ``rosdep`` command fails with a comment that binary packages can not be found by apt, try to update your rosdep index using ``rosdep update`` command or even your package index using ``sudo apt update``.
 
-5. You can then build your workspace using the alias for colcon build:
+4. You can then build your workspace using the alias for colcon build:
 
 .. code-block:: bash
 
-    cb
+   cb
 
 Everything should now have been built successfully!
 
-Next let's add another workspace
+5. Next let's add another workspace
 
 .. code-block:: bash
 
-   setup-ros-workspace ~/workspace/ws_rolling_gz_demos rolling
+   rtw workspace create \
+      --ws-folder ~/workspace/ws_rolling_gz_demos \
+      --ros-distro rolling
 
-Now repeat the above steps to add `gz_ros2_control <https://github.com/ros-controls/gz_ros2_control>`_ repository for testing and execute a demo from there.
+6. Now repeat the above steps to add `gz_ros2_control <https://github.com/ros-controls/gz_ros2_control>`_ repository for testing and execute a demo from there.
 
 .. note:: if ``rosdep`` commands fails with a comment on ros-rolling-ros-gz-sim not being installed successfully, maybe force the desired gazebo version with e.g. ``export GZ_VERSION=fortress``
 
-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.
+.. important::
+   Now each time you open a new terminal you can use either ``rtw ws ws_rolling_ros2c_demos`` or ``rtw ws 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.
diff --git a/docs/tutorials/quick-start.rst b/docs/tutorials/quick-start.rst
@@ -1,5 +1,5 @@
 ==================================
-Quick start with RosTeamWorkspace
+Quick start with RTW
 ==================================
 .. _tutorial-quick-start:
 
@@ -12,15 +12,15 @@ interested in:
    :maxdepth: 1
 
 
-Clone and source the RosTeamWorkspace
----------------------------------------
+Clone, setup and source the RosTeamWorkspace (RTW)
+---------------------------------------------------
 .. code-block:: bash
 
    git clone https://github.com/StoglRobotics/ros_team_workspace.git
+   cd ros_team_workspace/rtwcli/ && pip3 install -r requirements.txt --break-system-packages && cd -
    source ros_team_workspace/setup.bash
    setup-auto-sourcing  # Make RosTeamWorkspace automatically sourced when open a new terminal (The best experience)
 
-
 Create new package in an existing workspace
 --------------------------------------------------------
 For more details check :ref:`use-case description <uc-new-package>`.
diff --git a/docs/tutorials/setting_up_rtw.rst b/docs/tutorials/setting_up_rtw.rst
@@ -3,22 +3,29 @@ Setting up RosTeamWorkspace
 ============================
 .. _tutorial-setting-up-rtw:
 
-Installation of RosTeamWS
+Installation of RTW
 """"""""""""""""""""""""""
-To start using RosTeamWS framework clone the repository to any location using:
+To start using RTW framework clone the repository to any location using:
 
 .. code-block:: bash
 
    git clone https://github.com/StoglRobotics/ros_team_workspace.git
 
+Install RTW CLI. This is a python-based CLI as for ROS 2 that makes it easier to use:
 
-Source the ``setup.bash``` in the top folder of RosTeamWorkspace:
+.. code-block:: bash
+
+   cd ros_team_workspace/rtwcli/  # enter the RTW-CLI folder
+   pip3 install -r requirements.txt --break-system-packages  # since Ubuntu 24.04 is this flag required as we are not using virtual environment
+   cd -  # go back to the folder where you cloned the RTW
+
+Source the ``setup.bash``` in the top folder of RTW:
 
 .. code-block:: bash
 
    source ros_team_workspace/setup.bash
 
-That's all. You are now set to use RosTeamWS. If you want to add auto-sourcing you can simply execute the following command:
+That's all. You are now set to use RTW. If you want to add auto-sourcing you can simply execute the following command:
 
 .. code-block:: bash
 
diff --git a/docs/use-cases/index.rst b/docs/use-cases/index.rst
@@ -3,7 +3,7 @@ Use Cases
 ===========
 .. _uc-index:
 
-The RosTeamWS support currently the following use-cases.
+The RTW support currently the following use-cases.
 Check the repository and PRs for other, undocumented use-cases.
 
 .. toctree::
diff --git a/docs/use-cases/operating_system/create_setup_workspace.rst b/docs/use-cases/operating_system/create_setup_workspace.rst
@@ -3,10 +3,10 @@ Setup a new Workspace
 ===========================
 .. _uc-setup-workspace:
 
-This use-case describes how to setup a new ROS workspace using scripts from the ROS Team Workspace (RosTeamWS) framework. Besides the creation of a local workspace, creation of a Ubuntu-based docker container is supported. For more details have a look below in the `Docker workspace`_ section.
+This use-case describes how to setup a new ROS workspace using scripts from the ROS Team Workspace (RTW) framework. Besides the creation of a local workspace, creation of a Ubuntu-based docker container is supported. For more details have a look below in the `Docker workspace`_ section.
 
 .. important::
-   If you want to use Ubuntu 24.04 and ROS 2 Jazzy and Rolling (from May 2024) then checkout :ref:`RosTeamWS CLI workspace setup<rtwcli-setup-workspace>`.
+   If you want to use Ubuntu 24.04 and ROS 2 Jazzy and Rolling (from May 2024) then checkout :ref:`RTW CLI workspace setup<rtwcli-setup-workspace>`.
 
 Local workspace
 ----------------
@@ -58,7 +58,7 @@ Recreate a container
 If you removed an image,  you can recreate it by switching into the ``.rtw_docker_defines`` folder inside your workspace and then executing the ``./recreate_docker.sh`` command. After the process is finished you should be able to normally start, reconnect and stop the container.
 
 .. note::
-  For more general questions on the usage of docker and the limitations of RosTeamWS in interacting with docker, have a look at our :ref:`docker related docs<docker-overview>`.
+  For more general questions on the usage of docker and the limitations of RTW in interacting with docker, have a look at our :ref:`docker related docs<docker-overview>`.
 
 CLI overview
 """""""""""""
diff --git a/docs/use-cases/ros2_control/setup_controller.rst b/docs/use-cases/ros2_control/setup_controller.rst
@@ -4,7 +4,7 @@ ros2_control: Setup controller package
 .. _uc-setup-ros2-controller:
 
 This use-case describes how to set up a controller for the ros2_control
-framework using scripts from ROS Team Workspace (RosTeamWS) framework.
+framework using scripts from ROS Team Workspace (RTW) framework.
 The scripts uses template files from
 ``templates/ros2_control/controller`` folder.
 The script creates a full skeleton of a controller with plugin description
diff --git a/docs/use-cases/ros2_control/setup_robot_hardware_interface.rst b/docs/use-cases/ros2_control/setup_robot_hardware_interface.rst
@@ -4,7 +4,7 @@ ros2_control: Setup robot's hardware package
 .. _uc-setup-ros2-control-hardware:
 
 This use-case describes how to set up a robot's hardware interface for the
-ros2_control framework using scripts from ROS Team Workspace (RosTeamWS)
+ros2_control framework using scripts from ROS Team Workspace (RTW)
 framework.
 
 ``ros2_control_setup-hardware-interface-package`` script accepts the file name
diff --git a/docs/use-cases/ros_packages/create_package.rst b/docs/use-cases/ros_packages/create_package.rst
@@ -3,7 +3,7 @@ Create New Package
 =====================
 .. _uc-new-package:
 
-This use-case describes how to create a new package using scripts from the ROS Team Workspace (RosTeamWS) framework.
+This use-case describes how to create a new package using scripts from the ROS Team Workspace (RTW) framework.
 
 
 General Script for Creating Packages
diff --git a/docs/use-cases/ros_packages/setup_robot_bringup_package.rst b/docs/use-cases/ros_packages/setup_robot_bringup_package.rst
@@ -4,7 +4,7 @@ Setup robot bringup
 .. _uc-setup-robot-bringup:
 
 This use-case describes how to set up a robot bringup package using scripts
-from ROS Team Workspace (RosTeamWS) framework.
+from ROS Team Workspace (RTW) framework.
 The package follows as far as possible best practices for
 `robot support packages <http://wiki.ros.org/Industrial/Tutorials/WorkingWithRosIndustrialRobotSupportPackages>`_
 from ROS-Industrial consortia. (**This has to be verified!**)
diff --git a/docs/use-cases/ros_packages/setup_robot_description_package.rst b/docs/use-cases/ros_packages/setup_robot_description_package.rst
@@ -4,7 +4,7 @@ Setup robot description
 .. _uc-setup-robot-description:
 
 This use-case describes how to set up a robot description package using
-scripts from ROS Team Workspace (RosTeamWS) framework.
+scripts from ROS Team Workspace (RTW) framework.
 The package follows as far as possible best practices for
 `robot support packages <http://wiki.ros.org/Industrial/Tutorials/WorkingWithRosIndustrialRobotSupportPackages>`_
 from ROS-Industrial consortia. (**This has to be verified!**)
diff --git a/docs/use-cases/ros_workspaces/aliases.rst b/docs/use-cases/ros_workspaces/aliases.rst
@@ -38,6 +38,7 @@ rosdi
 
 Installling dependencies
 ^^^^^^^^^^^^^^^^^^^^^^^^
+.. _uc-aliases-dependencies:
 
 rosdepi
   Installing dependencies for the packages in ``$ROS_WS/src`` folder.
diff --git a/scripts/_RosTeamWs_Defines.bash b/scripts/_RosTeamWs_Defines.bash
@@ -129,7 +129,7 @@ function RosTeamWS_setup_aliases {
   alias rosds="cd \$ROS_WS/src"
   alias rosdb="cd \$ROS_WS/build"
   alias rosdi="cd \$ROS_WS/install"
-  alias rosdepi="rosdep install -y -i --from-paths \$ROS_WS/src"
+  alias rosdepi="rosdep install -r -y -i --from-paths \$ROS_WS/src"
 }
 
 function RosTeamWS_setup_ros1_exports {
