From 71a330e188382e07e7d3e1e9f709cc277c0d0682 Mon Sep 17 00:00:00 2001
From: "Dr. Denis" <denis@stoglrobotics.de>
Date: Tue, 21 Mar 2023 16:32:36 +0100
Subject: [PATCH] Add doc about standard aliases in RTW. (#113)

Co-authored-by: muritane <31107191+muritane@users.noreply.github.com>
---
 docs/use-cases/index.rst                  |   1 +
 docs/use-cases/ros_workspaces/aliases.rst | 100 ++++++++++++++++++++++
 2 files changed, 101 insertions(+)
 create mode 100644 docs/use-cases/ros_workspaces/aliases.rst

diff --git a/docs/use-cases/index.rst b/docs/use-cases/index.rst
index ddc6a3ab..e5d0422e 100644
--- a/docs/use-cases/index.rst
+++ b/docs/use-cases/index.rst
@@ -13,3 +13,4 @@ Check the repository and PRs for other, undocumented use-cases.
    operating_system/*
    ros_packages/*
    ros2_control/*
+   ros_workspaces/*
diff --git a/docs/use-cases/ros_workspaces/aliases.rst b/docs/use-cases/ros_workspaces/aliases.rst
new file mode 100644
index 00000000..cdfc7421
--- /dev/null
+++ b/docs/use-cases/ros_workspaces/aliases.rst
@@ -0,0 +1,100 @@
+=====================
+RTW Aliases
+=====================
+.. _uc-aliases:
+
+Standard RTW Aliases
+=====================
+
+Standard RTW aliases are configured out-of-the-box and they enable you to use the same command independently of the workspace you are in and help you hide ``colcon`` complexities and minimize errors when interacting with it.
+The aliases set for each workspace (see :ref:`ṁanaging multiple workspaces <tutorial-managing-multiple-workspaces>`) setup environment variables so that following aliases can interact with that specific workspace.
+
+
+Explanation of Standard Aliases
+--------------------------------
+The standard aliases are callable from any folder as long as a workspace is sourced using ``_<workspace_name>`` alias.
+
+.. note:: To make this reading short, Dr. Denis's favorite aliases are ``cb``, ``ca`` and ``crm`` - simply start with using those.
+
+
+Entering Workspace Folders
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+rosd
+  Enter the root directory of the ROS workspace.
+  Alias for command: ``cd $ROS_WS``
+
+rosds
+  Enter ``src`` directory of the ROS workspace.
+  Alias for command: ``cd $ROS_WS/src``
+
+rosdb
+  Enter ``build`` directory of the ROS workspace.
+  Alias for command: ``cd $ROS_WS/build``
+
+rosdi
+  Enter ``install`` directory of the ROS workspace.
+  Alias for command: ``cd $ROS_WS/install``
+
+
+Building Packages in Workspace
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Every alias has optional package names. If none is provided the whole workspace is built.
+
+cb [package1_name, package2_name]
+  Building named packages or the whole workspace.
+  Alias for command: ``colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=RelWithDebInfo``.
+
+cbup [package1_name, package2_name]
+  Building all packages up the named package (build all dependencies).
+  Alias for command: ``colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=RelWithDebInfo --packages-up-to``.
+
+cbd [package1_name, package2_name]
+  Building named packages or the whole workspace as *Debug* build type.
+  Alias for command: ``colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Debug``.
+
+cbr [package1_name, package2_name]
+  Building named packages or the whole workspace as *Release* build type.
+  Alias for command: ``colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release``.
+
+
+Executing Package Tests
+^^^^^^^^^^^^^^^^^^^^^^^^
+Every alias has optional package names. If none is provided the whole workspace is built.
+
+ct [package1_name, package2_name]
+  Testing named packages or the whole workspace.
+  Alias for command: ``colcon test``.
+
+ctup [package_name]
+  Testing named packages up to the workspace (build all dependencies).
+  Alias for command: ``colcon test --packages-up-to``.
+
+ctres [package_name]
+  Get test results for the whole workspace or a package. If using package the output will be ``grep``-processed to filter-out the package you are looking for.
+  Alias for command: ``colcon test-result --all``
+
+
+Executing Multiple Commands
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Every alias has optional package names. If none is provided the whole workspace is built.
+
+ca [package1_name, package2_name]
+  Build, test and show test results for the named packages or the whole workspace.
+
+caup [package_name]
+  Build, test and show test results for the package and all its dependencies.
+
+
+Cleaning Workspace
+^^^^^^^^^^^^^^^^^^^
+
+crm [package1_name, package2_name]
+  Remove ``build``, ``log`` and ``install`` folders for the workspace or corresponding sub-folders for specific packages.
+
+
+Defining Your Own Aliases
+===========================
+
+**TBD**
+
+Idea: sharing aliases with your team that are very specific for your use-cases.