[Doc] Full review and update (#133)

Co-authored-by: Dr. Denis <denis@stoglrobotics.de>

README.md

@@ -1,7 +1,7 @@
 # ros_team_workspace
 
 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/).
-It supports both **ROS1** and **ROS2**.
+It supports both **ROS** and **ROS 2**.
 Its main goal is to optimize the workflow of development teams and focus more on programming robots.
 
 [![Licence](https://img.shields.io/badge/License-Apache%20License%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
@@ -29,23 +29,23 @@ This package targets the following stakeholders:
 
 **The framework is the main entry-point for teams to**:
 
-#. organize their public and private ROS packages;
-#. describes scenarios;
-#. enable continuous integration across the use-cases;
-#. and provide scripts for easy use of ROS.
+1. organize their public and private ROS packages;
+2. describes scenarios;
+3. enable continuous integration across the use-cases;
+4. and provide scripts for easy use of ROS.
 
 
 **To achieve this, RosTeamWS defines**:
 
-#. an architecture of overlaid workspaces for sharing standard ROS packages;
-#. standardized package structure for straightforward collaboration;
-#. scripts for workspace and package management to keep their internal structure familiar to everyone in the team;
-#. often-used scripts for tests of small development-chunks.
+1. an architecture of overlaid workspaces for sharing standard ROS packages;
+2. standardized package structure for straightforward collaboration;
+3. scripts for workspace and package management to keep their internal structure familiar to everyone in the team;
+4. often-used scripts for tests of small development-chunks.
 
 
-The framework is initiated by Denis Stogl (2017-2020) for increasing collaboration at the Institute for Anthropomatics and Robotics (IAR) - Intelligent Process Control and Robotics (IPR) of Karlsruhe Institute of Technology (KIT).
+The framework was initiated by Dr. Denis (2017-2020) for increasing collaboration at the Institute for Anthropomatics and Robotics (IAR) - Intelligent Process Control and Robotics (IPR) of Karlsruhe Institute of Technology (KIT).
 
-From the 2021 the framework is maintained by Stogl Robotic Consulting.
+From 2021, the framework is maintained by Stogl Robotics Consulting.
 
 DISCLAIMER
 -------------

docs/docker/docker_use_cases/docker_use_cases.rst

@@ -3,7 +3,7 @@ Use Cases with docker support
 ==============================
 .. _uc-with-docker-support-index:
 
-All use cases with docker suppert are listed below. For a detailed description of the use case as well as the respective commands, you can click on the link in the use case column.
+All use cases with docker support are listed below. For a detailed description of the use case as well as the respective commands, you can click on the link in the use case column.
 
 .. list-table:: Overview of currently supported use cases
    :widths: auto

docs/docker/general_information_docker/general_information_docker.rst

@@ -5,8 +5,8 @@ General information on docker
 
 Generally you can always have a look at the `docs of docker <https://docs.docker.com/>`_.
 
-Installation
-""""""""""""""""
+Installation of Docker
+"""""""""""""""""""""""
 .. _general-info-on-docker-installation:
 
 You have to install docker which is dependent on the operating system you are using.
@@ -28,7 +28,7 @@ which should print out a "Hello from Docker!" message.
 
 Useful commands
 """"""""""""""""
-For complete list of commands have a look at `official docker cli reference <https://docs.docker.com/engine/reference/commandline/cli/>`_.
+For a complete list of commands have a look at `official docker cli reference <https://docs.docker.com/engine/reference/commandline/cli/>`_.
 
 * ``docker container <command>``:
 

docs/docker/index.rst

@@ -15,4 +15,4 @@ RosTeamWS supports the usage of docker containers.
    supported_versions/*
 
 .. note::
-  If you want to forward a xsession from docker (e.g. rviz2), you have to install xhost.
+  If you want to forward an *xsession* from docker (e.g. rviz2), you have to install *xhost*.

docs/docker/nvidia_docker/setup_nvidia_support.rst

@@ -12,7 +12,7 @@ Before we can install the NVIDIA Container Toolkit we have to install the nvidia
 **NOTE**: Check the end of the file for some tips about throubleshoting.
 
 Nvidia drivers
-----------------
+---------------
 Make sure you have the NVIDIA drivers for your Linux distribution installed. This can either be done by using your package manager or you can download the ``.run`` installers from `NVIDIA Driver Downloads <https://www.nvidia.com/Download/index.aspx?lang=en-us>`_.
 This depends on the operating system and package manager you are using so you have to look it up.
 You can then check your drivers by typing
@@ -47,8 +47,8 @@ Which should print something like this:
   |    0   N/A  N/A      2516      G   ....0.2/bin/.firefox-wrapped      144MiB |
   +-----------------------------------------------------------------------------+
 
-Docker
-----------------
+Docker installation
+--------------------
 .. _docker-nvidia-support-prerequisites_docker:
 
 Make sure docker is installed and it's working correctly. For instructions on how to install docker have a look :ref:`in general info on docker installation <general-info-on-docker-installation>`.

docs/faq/index.rst

@@ -5,9 +5,9 @@ FAQ
 On Docker
 ----------------
 
-How to forward a xsession
+How to forward an xsession
 """""""""""""""""""""""""""""
-If you want to forward a xsession from docker (e.g. rviz2), you have to install xhost.
+If you want to forward an xsession from docker (e.g. rviz2), you have to install xhost.
 The forwarding is done automatically by adding docker user to the X Server access list when docker is created.
 
 
@@ -20,6 +20,6 @@ sudo: unable to resolve host <hostname>: Name or service not known
 """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 Problem using sudo: If you encounter following message trying to use sudo: ``sudo: unable to resolve host <hostname>: Name or service not known``. You have to add ``127.0.0.1 <hostname>`` to the ``/etc/hosts`` file inside the container. However, using sudo should work fine without adding it.
 
-Docker and ROS1: Can not start my roscore.
-""""""""""""""""""""""""""""""""""""""""""
+Docker and ROS (ROS1): Can not start my roscore.
+"""""""""""""""""""""""""""""""""""""""""""""""""
 If you try to start your roscore inside the docker container with ``roscore``-command and get the following error message: ``RLException: Unable to contact my own server at [http://<hostname>:<port>]``. You have to add ``127.0.0.1 <hostname>`` to the ``/etc/hosts`` file inside the container.

docs/guidelines/development.rst

@@ -5,7 +5,7 @@ Development Guidelines
 
 This documents proposes development guidelines to increase work efficiency and synergy within the rest of the team.
 
-**NOTE**: All the proposal here are the results of authors' personal experiences. Saying that, if you have any idea to make them better you are very wellcome to create a PR.
+**NOTE**: All the proposal here are the results of authors' personal experiences. Saying that, if you have any idea to make them better you are very welcome to create a PR.
 
 Overview
 =========
@@ -19,21 +19,21 @@ Code Changes and Pull Request Submissions
 ==========================================
 
 To make a change of the existing code base, Pull Request (GitHub) or Merge Request (GitLab) are used.
-This section describes in short process with valuable tips to make your and reviewers' life easier.
+This section describes in short the process with valuable tips to make your and reviewers' life easier.
 
-#. Check with the team if it is usual to submit a PR/MR from a fork or directly into target repository.
+#. Check with the team if it is usual to submit a PR/MR from a fork or directly into the target repository.
    This usually depends on the team size and organization.
    When working with public repositories you always need to create a fork.
 
    .. note::
 
       In *Stogl Robotics* we have the organization called `StoglRobotics-forks <https://github.com/StoglRobotics-forks>`_ where all forks of public repositories live and are accessible for writing by all team members.
-      This simplify collaboration inside the team - there is no need for individual access grants when using forks under your user.
+      This simplifies collaboration inside the team - there is no need for individual access grants when using forks under your user.
       **Always** check if there is already a fork in *StoglRobotics-forks* organization and if not create it.
 
 #. Start development always from the up-to date state of the repositories default branch (usually called *master* or *main* - for simplicity we call it *master* here).
-   Take into account that master branch of your fork is usually not up to date with the upstream repository.
-   Therefore be careful about that and use the opportunity to sync *master* branch of the fork to the state of the *master* branch of the upstream repository.
+   Take into account that the master branch of your fork is usually not up to date with the upstream repository.
+   Therefore be careful about that and use the opportunity to sync the *master* branch of the fork to the state of the *master* branch of the upstream repository.
 
 #. **Always** create a new branch for each feature or bug fix.
    **Never** make multiple changes on a same feature branch. One feature / change == one branch. Don't submit PRs from *master* branch.
@@ -43,18 +43,18 @@ This section describes in short process with valuable tips to make your and revi
 
    .. note::
 
-      In *Stogl Robotics* we are always *squashing* commits, i.e., one future or one bug fix is one commit in the default branch. The commit message is edited before merging.
+      In *Stogl Robotics* we are always *squashing* commits, i.e., one future or one bug fix is one commit in the default branch. The commit message is edited before merging. Make sure the commit message retains relevant information of the commits to be squashed (e.g. non-trivial reason why a change was made)
 
 #. Explain in the PR/MR description what your code is doing and why.
 
 #. When you are finished with development and want to submit code for the review - consider the following tips:
 
    - **Always** run *pre-commit* formatters;
    - Review your code **first by yourself** before asking someone else;
-   - Make sure there **are not** commented code blocks or if they have to be there add explanation why;
+   - Make sure there **are no** commented code blocks or if they have to be there, add explanations why;
    - Resolve all TODOs or add concrete questions about them either in the code or in review comments so that other people know this is open for discussion;
    - By iterating on the review adjust **all parts** of the code with the same or similar patterns even if you get a comment about those only in one place - reviewers usually don't like to repeat themselves on each iteration of the same issue - if you are not sure about something, ask;
-   - Ask yourself: *Would I like to review this code?*.
+   - Ask yourself: *Would I like to review this code ?*.
 
    .. important::
 
@@ -65,7 +65,7 @@ This section describes in short process with valuable tips to make your and revi
 Use *pre-commit* for formatting and linting
 ============================================
 
-``pre-commit`` is a program that adds hooks into ``git`` so when you commit something actions can be automatically executed.
+``pre-commit`` is a program that adds hooks into ``git`` so when you commit something, actions can be automatically executed.
 There are many different possibility with ``pre-commit`` but it is mostly used for integrating code linters and formatters to always commit clean code.
 
 Getting started with *pre-commit*
@@ -88,8 +88,8 @@ This will execute ``pre-commit`` on every commit you make and prevent it from do
 If you really need to ignore check in the commit, you can add ``-n`` flag to the ``git commit`` command and they will be skipped.
 
 
-**NOTE**: If your repository does not uses ``pre-commit`` yet, it is very easy to add it by creating a configuration file ``.pre-commit-config.yaml`` in the top level of your repository (there where ``.git`` folder is).
-If you don't know where to start with *pre-commit* configuration in your ROS project, simply copy our template from `templates/package/.pre-commit-config.yaml <https://github.com/StoglRobotics/ros_team_workspace/blob/master/templates/package/.pre-commit-config.yaml>`_.
+.. note:: If your repository does not use ``pre-commit`` yet, it is very easy to add it by creating a configuration file ``.pre-commit-config.yaml`` in the top level of your repository (there where ``.git`` folder is).
+          If you don't know where to start with *pre-commit* configuration in your ROS project, simply copy our template from `templates/package/.pre-commit-config.yaml <https://github.com/StoglRobotics/ros_team_workspace/blob/master/templates/package/.pre-commit-config.yaml>`_.
 
 
 Useful commands and options

docs/guidelines/robot_package_structure.rst

@@ -2,14 +2,14 @@
 ROS-Robot Package structure
 ============================
 
-This documents proposes guidelines for structure of ROS packages in larger detail than provided by `ROS Enhancement Proposals (REPs) <https://github.com/ros-infrastructure/rep>`_
+This document proposes guidelines for the structure of ROS packages in larger details than provided by `ROS Enhancement Proposals (REPs) <https://github.com/ros-infrastructure/rep>`_
 
 **NOTE**: All the proposal here are the resuls of authors' personal experiences. Saying that, if you don't like some of it, you are free to change what you want and need (and hopefully propose it as PR).
 
 Package structure for Robot support in ROS
 ------------------------------------------
 
-Here proposed architecture try to split the robot's files to minimize per-package dependencies.
+The here down proposed architecture tries to split the robot's files to minimize per-package dependencies.
 
 .. code:: text
 
@@ -20,8 +20,8 @@ Here proposed architecture try to split the robot's files to minimize per-packag
   ├── <robot_name>_bringup/                              # Launch and config files for starting the robot using ros2_control
   │   ├── [CMakeLists.txt]                               # if ament_cmake is used (recommended)
   │   ├── package.xml
-  │   ├── [setup.py]                                     # if amend_python is used
-  │   ├── [setup.cfg]                                    # if amend_python is used
+  │   ├── [setup.py]                                     # if ament_python is used
+  │   ├── [setup.cfg]                                    # if ament_python is used
   │   ├── config/
   │   │   ├── <robot_name>_controllers.yaml              # Controllers' configuration for ros2_control
   │   │   ├── <robot_name>_forward_position_publisher.yaml  # Setup test publisher for forward position controller
@@ -33,8 +33,8 @@ Here proposed architecture try to split the robot's files to minimize per-packag
   ├── <manufacturer|robot_name>_description/             # Robot's description files
   │   ├── [CMakeLists.txt]                               # if ament_cmake is used (recommended)
   │   ├── package.xml
-  │   ├── [setup.py]                                     # if amend_python is used
-  │   ├── [setup.cfg]                                    # if amend_python is used
+  │   ├── [setup.py]                                     # if ament_python is used
+  │   ├── [setup.cfg]                                    # if ament_python is used
   │   ├── config/                                        # general YAML files for a robot
   │   │   └── <robot_name>_<someting_specific>.yaml
   │   ├── launch/                                        # launch files related to testing robots' description

docs/index.rst

@@ -3,12 +3,12 @@ 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/>`_.
-It supports both **ROS1** and **ROS2**.
+It supports both **ROS** and **ROS 2**.
 Its main goal is to optimize the workflow of development teams and focus more on programming robots.
 
-The framework is initiated by Denis Stogl in 2016 to increase collaboration at the Institute for Anthropomatics and Robotics (IAR) - Intelligent Process Control and Robotics (IPR), Karlsruhe Institute of Technology (KIT).
+The framework was initiated by Dr. Denis in 2016 to increase collaboration at the Institute for Anthropomatics and Robotics (IAR) - Intelligent Process Control and Robotics (IPR), Karlsruhe Institute of Technology (KIT).
 
-From the 2021 the framework is maintained by Stogl Robotic Consulting.
+From 2021, the framework is maintained by Stogl Robotics Consulting.
 
 .. .. contents:: Table of Contents
 ..    :depth: 2
@@ -30,7 +30,7 @@ The framework is the main entry-point for teams to:
 #. organize their public and private ROS packages;
 #. describes scenarios;
 #. enable continuous integration across the use-cases;
-#. and provide scripts for easy use of ROS.
+#. provide scripts for easy use of ROS.
 
 
 To achieve this, RosTeamWS defines:

docs/tutorials/managing_multiple_workspaces.rst

@@ -3,7 +3,7 @@ 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>`.
+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>`.
 
 Also be sure that you opened a new terminal after you setup RosTeamWorkspace to be configured permanently.
 
@@ -15,7 +15,7 @@ First setup a new workspace called ``ws_rolling_ros2c_demos`` inside a ``~/works
    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``.
+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.
 
@@ -42,9 +42,9 @@ Let's now add a test package into your workspace.
 
     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``.
+.. 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:
+5. You can then build your workspace using the alias for colcon build:
 
 .. code-block:: bash
 
@@ -58,6 +58,8 @@ Next let's add another workspace
 
    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 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.