refactor(setup): improve/fix wording in scripts/docs

bitbots_misc/bitbots_docs/docs/manual/tutorials/install_software_ros2.rst

@@ -3,26 +3,18 @@ Software installation with ROS2
 
 In this tutorial, we will learn how to install ROS2 Iron Irwini on Ubuntu 22.04 and build our software stack.
 
-
-**0. Use Ubuntu 22.04**
-
-As ROS works best on Ubuntu, we are using this distribution.
-Currently, ROS2 Iron runs on Ubuntu 22.04.
-If you are not already using Ubuntu 22.04, consider installing it on your system (perhaps as a dual boot), alternately you can run it in a virtual machine (not recommended, as recently we had some issues with it; https://www.virtualbox.org/), a custom ROS2 docker setup (https://github.com/timonegk/rosdocked).
-
-Alternatively you can use a devcontainer :doc:`vscode-dev-container`, with a preconfigured environment and follow those instructions, as these docs do not apply to the devcontainer.
-
 **TLDR**: single command setup
 ------------------------------
 
 **Prerequirements**
-- running Ubuntu 22.04 environment (native, VM, or custom ROS2 docker setup)
-- existing Github account and with SSH key added to your account
-- root access to your system (sudo)
+- You have a running Ubuntu 22.04 environment
+- You have an existing Github account and added a SSH key to your account
+- You have root access to your system (sudo)
 
 If you have not previously set up any of our software stack, you can use the following command to install and setup everything in one go:
 
 .. code-block:: bash
+
   mkdir -p ~/git/bitbots \
     && cd ~/git/bitbots \
     && curl -fsSL https://raw.githubusercontent.com/bit-bots/bitbots_main/main/scripts/setup.sh > /tmp/setup.sh \
@@ -31,6 +23,14 @@ If you have not previously set up any of our software stack, you can use the fol
 Manual steps with in depth explanation
 --------------------------------------
 
+**0. Use Ubuntu 22.04**
+
+As ROS works best on Ubuntu, we are using this distribution.
+Currently, ROS2 Iron runs on Ubuntu 22.04.
+
+If you are not already using Ubuntu 22.04, consider installing it on your system (perhaps as a dual boot?).
+Alternatively you can use a devcontainer :doc:`vscode-dev-container`, with a preconfigured environment and follow those instructions, as these docs do not apply to the devcontainer.
+
 **1. Setup and Install ROS 2**
 
 - Follow this guide and when it comes to the section **Install ROS 2 packages**, install the recommended ``ros-iron-desktop-full``: https://docs.ros.org/en/iron/Installation/Ubuntu-Install-Debians.html
@@ -51,9 +51,10 @@ Manual steps with in depth explanation
     ros-iron-rqt-robot-monitor \
     ros-iron-rqt-runtime-monitor
 
-- To aditionally get nice colored output from colcon, you can install the following pip packages:
+- Optionally, to get nice colored output from colcon, you can install the following pip packages:
 
 .. code-block:: bash
+
   python3 -m pip install \
     git+https://github.com/ruffsl/colcon-clean \
     git+https://github.com/timonegk/colcon-core.git@colors \
@@ -68,8 +69,7 @@ If you want to install it, you can do so by running ``make webots`` in the bitbo
 
 **3. Download our software**
 
-- Create a GitHub account, if not already done (see here for further information on this: http://doku.bit-bots.de/private/manual/dienste_accounts.html)
-  Those services host our Git software repositories.
+- Create a GitHub account, if not already done (see `here <http://doku.bit-bots.de/private/manual/dienste_accounts.html>` for further information)
 - Add your SSH key to GitHub to access and sync our repositories
     - If you don't know what I am talking about or you don't yet have a SSH key, follow this guide: https://docs.github.com/en/authentication/connecting-to-github-with-ssh/checking-for-existing-ssh-keys
     - Go to your account settings and add your SSH key (the ``.pub`` file) to `GitHub <https://github.com/settings/keys>`_
@@ -105,6 +105,8 @@ In case you are not using the bash shell, replace ``~/.bashrc`` and ``bash`` wit
 
   cat >> ~/.bashrc << EOF
 
+  # >>> bit-bots initialize >>>
+
   # Ignore some deprecation warnings
   export PYTHONWARNINGS=ignore:::setuptools.command.install,ignore:::setuptools.command.easy_install,ignore:::pkg_resources
 
@@ -135,3 +137,13 @@ In case you are not using the bash shell, replace ``~/.bashrc`` and ``bash`` wit
   EOF
 
 - Configure the robot hostnames, see :doc:`configure_hostnames`.
+
+Notes
+-----
+
+Custom docker setup
+  Before utilizing a devcontainer, we used a custom docker setup for ROS 2 development.
+  If you want (or need) to utilize a custom setup like this, have a look at https://github.com/timonegk/rosdocked.
+
+Virtual Machine setup
+  We recommend against using a virtual machine for ROS 2 development, both for compile speed and setup complexity reasons.

scripts/ros.plugin.sh

@@ -1,4 +1,4 @@
-### Aliases and functions for ros2/colcon usage. Usage for either
+### Aliases and functions for ROS 2 and colcon usage. Usage for either
 ### Ubuntu 22.04 or in rosdocked/dev docker container
 
 shell="$(basename "$SHELL")"
@@ -8,9 +8,9 @@ rid() {
   echo "ROS_DOMAIN_ID set to $ROS_DOMAIN_ID"
 }
 
-# Create a function to update the argcomplete so tab completion works
-# This needs to be called every time we source something ROS 2 related
-# For this previous loading of bashcompinit is required
+# Create a function to update the argcomplete so tab completion works.
+# This needs to be called every time we source something ROS 2 related.
+# Previous loading of bashcompinit is required.
 update_ros2_argcomplete() {
   eval "$(register-python-argcomplete3 colcon)"
   eval "$(register-python-argcomplete3 ros2)"

scripts/setup.sh

@@ -131,7 +131,7 @@ build_repository() {
 }
 
 setup_shell_aliases() {
-    if ask_question "Do you want to setup/update the bit-bots ros2/colcon shell configuration?"; then
+    if ask_question "Do you want to setup/update the Bit-Bots ROS 2 and colcon shell configuration?"; then
         local shell_config_file
 
         if [[ "$SHELL" =~ "bash" ]]; then
@@ -154,7 +154,7 @@ if ask_question "Do you have sudo rights?"; then
     has_sudo=1
 fi
 if (( ! has_sudo )); then
-    echo "Because, you don't have sudo rights, you need ensure all necessary ros packages are preinstalled."
+    echo "Because, you don't have sudo rights, ensure all necessary ROS 2 packages are installed."
 fi
 
 in_repo=1