Merge branch 'master' into destogl-patch-2

docs/conf.py

@@ -72,7 +72,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

docs/index.rst

@@ -54,4 +54,5 @@ The opinions and proposals stated here are merely related to the authors' experi
    guidelines/index.rst
    use-cases/index.rst
    docker/index.rst
+   rtwcli/index.rst
    faq/index.rst

docs/requirements.txt

@@ -1,5 +1,5 @@
 pip
-sphinx==4.3.2
+sphinx==5.0
 sphinx-copybutton
 sphinx-multiversion
 sphinx-rtd-theme

docs/rtwcli/index.rst

@@ -0,0 +1,133 @@
+==============================
+RosTeamWS CLI (Experimental)
+==============================
+
+RosTeamWS 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
+""""""""""""""""""""""""
+
+Follow the instructions in the ``README.md`` inside the ``rtwcli`` folder.
+
+
+How to use the CLI
+""""""""""""""""""""
+
+The CLI currently supports the following commands:
+
+* ``rtw workspace``: Various workspace related sub-commands
+   * ``create``: Create a new ROS workspace (local or dockerized)
+   * ``use``: Select and source an existing ROS workspace
+   * ``port``: Port existing RTW workspace(s)
+
+* ``rtw docker``: Various Docker related sub-commands
+   * ``enter``: Enter a Docker container for a dockerized workspace
+
+* ``rtw ws``: Alias for ``rtw workspace use``
+
+.. note::
+   For more detailed usage of each command or sub-command, run
+   ``rtw <command> -h`` or ``rtw <command> <sub-command> -h``.
+
+
+Setting up a new workspace from ``.repos`` files
+"""""""""""""""""""""""""""""""""""""""""""""""""
+
+PR `#169 <https://github.com/RosTeamWS/RosTeamWS/pull/169>`_ introduced a new
+feature to create a new workspace (local or dockerized) from ``.repos`` files,
+streamlining the setup process for complex projects with multiple repositories.
+
+* Usage:
+   * ``rtw workspace create``
+     ``--ws-folder <path_to_workspace>``
+     ``--ros-distro <distribution>``
+     ``[options]``
+   * Main ``[options]``:
+      * ``--docker``: Create workspace(s) in a docker environment
+      * ``--repos-containing-repository-url <url>``: URL of the repository
+        containing the ``.repos`` files
+        * Main ws repos format: ``{repo_name}.{ros_distro}.repos``
+        * Upstream ws repos format: ``{repo_name}.{ros_distro}.upstream.repos``
+      * ``--repos-branch <branch>``: Branch of the repository containing the
+        ``.repos`` files
+
+* Example:
+
+.. code-block:: bash
+
+   rtw workspace create \
+      --ws-folder dummy_ws \
+      --ros-distro humble \
+      --docker \
+      --repos-containing-repository-url \
+         [email protected]:StoglRobotics/sr_dummy_packages.git \
+      --repos-branch dummy_demo_pkg
+..
+
+   * This command will create a new dockerized workspace named ``dummy_ws``
+     with ROS distribution ``humble`` using the ``.repos`` files from the
+     repository ``sr_dummy_packages`` on branch ``dummy_demo_pkg``.
+
+* Example of a ``standalone`` workspace and ``robot`` user:
+
+.. code-block:: bash
+
+   rtw workspace create \
+      --ws-folder dummy_ws \
+      --ros-distro humble \
+      --docker \
+      --repos-containing-repository-url \
+         [email protected]:StoglRobotics/sr_dummy_packages.git \
+      --repos-branch dummy_demo_pkg \
+      --standalone \
+      --user-override-name robot
+..
+
+   * This command will create a new dockerized standalone workspace named
+     ``dummy_ws`` with ROS distribution ``humble`` using the
+     ``.repos`` files from the repository ``sr_dummy_packages`` on branch
+     ``dummy_demo_pkg``.
+
+     However, for exporting the workspace docker image, the commit command must
+     be executed first:
+
+     .. code-block:: bash
+
+         docker commit rtw_dummy_ws_final-instance rtw_dummy_ws_export
+
+     When importing the workspace docker image, the following command must be
+     executed:
+
+     .. code-block:: bash
+
+         rtw workspace import \
+            --ws-name dummy_import_ws \
+            --ros-distro humble \
+            --standalone-docker-image rtw_dummy_ws_export \
+            --user-override-name robot
+
+     The ``--user-override-name`` flag is necessary to create the user with
+     the same name as the one used in the exported workspace.
+
+.. important::
+   After PC restart, the ``.xauth`` cookie file will be removed. Therefore,
+   before attaching VSCode, execute ``rtw ws <ws-name>`` and
+   ``rtw docker enter`` to create the necessary ``.xauth`` cookie file.
+
+.. note::
+   After creating a new dockerized workspace, the rocker will start interactive
+   bash session in the container.
+
+   Only after exiting the container, the
+   corresponding workspace config will be saved.
+
+   This is done due to the fact that the setting up of the rocker container
+   fails often.

rtwcli/README.md

@@ -10,7 +10,7 @@
 
 > [!NOTE]
 > If `rtw` command is not available, then add this to `~/.bashrc`:
-> `export PATH=${PATH}:~/.local/bin`
+> `export PATH=${PATH}:${HOME}/.local/bin`
 
 ## porting workspace
 
@@ -23,3 +23,8 @@ source your workspace: `_<ws_name>`
 port config: `rtw wokspace port`
 
 test porting: `rtw wokspace use`
+
+
+## For converting https to ssh:
+> [!NOTE]
+> `git config --global url."[email protected]:".insteadOf "https://github.com/"`

rtwcli/requirements.txt

@@ -1,2 +1,3 @@
 -e ./rtwcli
 -e ./rtw_cmds
+-e ./rtw_rocker_extensions

rtwcli/rtw_cmds/rtw_cmds/aliases.py

@@ -14,7 +14,7 @@
 
 import argparse
 from rtwcli.command import CommandExtension
-from rtw_cmds.workspace.verbs import UseVerb, add_cli_workspace_args
+from rtw_cmds.workspace.use_verb import UseVerb, add_rtw_workspace_use_args
 
 
 class WSAlias(CommandExtension):
@@ -24,7 +24,7 @@ def __init__(self):
         super().__init__()
 
     def add_arguments(self, parser: argparse.ArgumentParser, cli_name: str):
-        add_cli_workspace_args(parser)
+        add_rtw_workspace_use_args(parser)
 
     def main(self, *, parser, args):
         use_verb = UseVerb()

rtwcli/rtw_cmds/rtw_cmds/docker/verbs.py

@@ -12,11 +12,40 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from rtwcli.docker_utils import (
+    docker_exec_interactive_bash,
+    docker_start,
+    fix_missing_xauth_file,
+    is_docker_container_running,
+)
 from rtwcli.verb import VerbExtension
+from rtwcli.workspace_utils import get_current_workspace
 
 
 class EnterVerb(VerbExtension):
     """Enter docker container."""
 
     def main(self, *, args):
-        print("Not implemented yet")
+        ws = get_current_workspace()
+        if not ws:
+            print("No workspace is active.")
+            return
+
+        if not ws.ws_docker_support:
+            print("The workspace does not support docker.")
+            return
+
+        if not is_docker_container_running(ws.docker_container_name):
+            print(
+                f"The docker container '{ws.docker_container_name}' is not running, starting it now."
+            )
+            # fix missing .xauth file if it is not present
+            if not fix_missing_xauth_file(ws.docker_container_name):
+                print(f"Failed to fix missing .xauth file for '{ws.docker_container_name}'.")
+                return
+
+            if not docker_start(ws.docker_container_name):
+                print(f"Failed to start docker container '{ws.docker_container_name}'.")
+                return
+
+        docker_exec_interactive_bash(ws.docker_container_name)