improve documentation & misc

- overhaul README
- standardize phrasing & naming used
- clarify, add & remove comments
- add python import sorting to settings.json

.devcontainer/devcontainer.json

@@ -1,28 +1,21 @@
-// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at:
-// https://github.com/microsoft/vscode-dev-containers/tree/v0.238.0/containers/docker-existing-docker-compose
+// Dev Container configuration.
+// For format details, see https://aka.ms/devcontainer.json.
+// For config options, see the README at:
+// https://github.com/microsoft/vscode-dev-containers/tree/main/containers/docker-existing-docker-compose
 {
+  // (OPTION) Change the name to help identify which workspace you are in.
   "name": "ROS2 Dev",
-  // Update the 'dockerComposeFile' list if you have more compose files or use different names.
-  // The .devcontainer/docker-compose.yml file contains any overrides you need/want to make.
   "dockerComposeFile": ["../docker-compose.yml", "../docker-compose.dev.yml"],
-  // The 'service' property is the name of the service for the container that VS Code should
-  // use. Update this value and .devcontainer/docker-compose.yml to the real service name.
   "service": "dev",
-  // The optional 'workspaceFolder' property is the path VS Code should open by default when
-  // connected. This is typically a file mount in .devcontainer/docker-compose.yml
   "workspaceFolder": "/code",
-  // Use 'forwardPorts' to make a list of ports inside the container available locally.
-  // "forwardPorts": [],
-  // Uncomment the next line if you want start specific services in your Docker Compose config.
-  // "runServices": [],
-  // Uncomment the next line if you want to keep your containers running after VS Code shuts down.
-  // "shutdownAction": "none",
+  // See: https://containers.dev/implementors/json_reference/#lifecycle-scripts
+  // Please follow the same method of creating shell scripts in the `hooks` folder.
   "postCreateCommand": ". /tmp/.devcontainer/hooks/postCreate.sh",
   "postStartCommand": ". /tmp/.devcontainer/hooks/postStart.sh",
-  // Uncomment to connect as a non-root user if you've added one. See https://aka.ms/vscode-remote/containers/non-root.
   "remoteUser": "user",
   "customizations": {
     "vscode": {
+      // Extensions suggested.
       "extensions": [
         "njpwerner.autodocstring",
         "bungcip.better-toml",

.devcontainer/hooks/postCreate.sh

@@ -1,12 +1,12 @@
 #!/bin/sh
+# `postCreate.sh` is called when the Dev Container is first created.
+# It can be used for setup steps outside the Dockerfile.
 
-# postCreate.sh is called after the container is created by devcontainer.json.
-# It can be used to install & setup tools not wanted in the Dockerfile.
+. /opt/ros/$ROS_DISTRO/setup.sh
 
-# This mitigates the Dockerfile somehow breaking the folder permissions.
+# Mitigates the Dockerfile somehow breaking folder permissions.
 sudo chown user:user /code
 
-. /opt/ros/$ROS_DISTRO/setup.sh
-# Something removed the package indexes so we download them again for convenience.
+# Something deleted the package indexes so we re-download them for convenience.
 sudo apt-get update
 sudo rosdep update

.devcontainer/hooks/postStart.sh

@@ -1,24 +1,23 @@
 #!/bin/sh
+# `postStart.sh` is called whenever the Dev Container starts.
+# It can be used for misc tasks (e.g., ensuring dependencies are installed).
 
-# postStart.sh is called every time the container starts by devcontainer.json.
-# It can be for misc tasks like ensuring all dependencies are installed.
+. /opt/ros/$ROS_DISTRO/setup.sh
 
-# Due to https://github.com/microsoft/vscode-remote-release/issues/6683
-# we have to explicitly trust workspace folder for git.
-# Due to https://github.com/microsoft/vscode-remote-release/issues/6810#issuecomment-1159354677
-# this cannot be done in Dockerfile (else VSCode fails to configure git in the container).
+# Due to https://github.com/microsoft/vscode-remote-release/issues/6683,
+# we have to disable git's repository trust feature.
+# Due to https://github.com/microsoft/vscode-remote-release/issues/6810#issuecomment-1159354677,
+# this cannot be done in the Dockerfile (else VS Code doesn't configure `.gitconfig`).
 git config --global safe.directory "*"
 
-. /opt/ros/$ROS_DISTRO/setup.sh
-
-# (Optional) Clone repo on first setup if using named volume to store repo.
+# If using named volume to store repository, clone and setup the repository.
 test -d "/code/.git" \
   || ( \
-    git clone "(Optional) Insert repo url" /code --recurse-submodules \
+    git clone "(OPTION) Insert repository url" /code --recurse-submodules \
     && cd /code \
     && git submodule foreach --recursive git checkout main \
   )
 
-# Ensure all dependencies are installed.
+# Ensure dependencies are installed.
 sudo rosdep install -i --from-path /code -y
 sudo pip install -r /code/requirements.txt

.dockerignore

@@ -1,7 +1,6 @@
-# You can partially generate this from .gitignore.
-# A online converter: https://codesandbox.io/s/7e9ox7
+# `.gitignore` to `.dockerignore` converter: https://codesandbox.io/s/7e9ox7
 
-# Don't ignore .devcontainer if using volume to store repository.
+# If using named volume to store repository, don't ignore `.devcontainer`.
 
 # Config & Others
 **/.vscode
@@ -19,5 +18,5 @@ log
 **/*.py[cod]
 **/*.lprof
 
-# Mount Points
+# (OPTION) Ignore mount points.
 # data

.gitignore

@@ -8,12 +8,12 @@ log/*
 __pycache__/
 *.py[cod]
 
-# VSCode
+# VS Code
 .vscode
 !.vscode/*.json
 
 # Profiling
 *.lprof
 
-# Mount Points
+# (OPTION) Ignore mount points.
 # data/*

.vscode/c_cpp_properties.json

@@ -1,3 +1,4 @@
+// VS Code configuration for ROS C/C++.
 {
   "configurations": [
     {

.vscode/extensions.json

@@ -1,3 +1,4 @@
+// Extensions suggested.
 {
   "recommendations": [
     "ms-vscode-remote.remote-containers",

.vscode/settings.json

@@ -1,3 +1,4 @@
+// VS Code configuration.
 {
   "python.autoComplete.extraPaths": [
     "/opt/ros/humble/lib/python3.10/site-packages",
@@ -10,5 +11,19 @@
   "python.languageServer": "Pylance",
   "ros.distro": "humble",
   "editor.formatOnSave": true,
-  "python.formatting.provider": "black"
+  // Use black by default for formatting Python code.
+  "python.formatting.provider": "black",
+  "editor.codeActionsOnSave": {
+    // Automatically sort imports by default.
+    "source.organizeImports": true
+  },
+  // Format Python imports in a way compatible with black.
+  // See: https://github.com/microsoft/vscode-python/issues/6933#issuecomment-543059396
+  "python.sortImports.args": [
+    "--multi-line=3",
+    "--trailing-comma",
+    "--force-grid-wrap=0",
+    "--use-parentheses",
+    "--line-width=88"
+  ]
 }

.vscode/tasks.json

@@ -3,7 +3,7 @@
   // for the documentation about the tasks.json format
   "version": "2.0.0",
   "tasks": [
-    // ROS extension is glitchy; separate tasks created for convenience.
+    // ROS extension is broken; Below tasks created for developer convenience.
     {
       "label": "rosdep install dependencies",
       "type": "shell",

Dockerfile

@@ -1,7 +1,7 @@
 # syntax=docker/dockerfile:1
 
 # Dockerfile for production
-# Referring to Dockerfile.dev might be useful for understanding the below.
+# Referring to Dockerfile.dev might be useful for understanding the contents.
 
 FROM nvidia/cuda:11.7.1-cudnn8-runtime-ubuntu22.04
 
@@ -10,7 +10,7 @@ ENV LANG="C.UTF-8" LC_ALL="C.UTF-8"
 RUN echo 'Etc/UTC' > /etc/timezone \
   && ln -s /usr/share/zoneinfo/Etc/UTC /etc/localtime
 
-# (Optional) Add VNC for debugging and control.
+# (OPTION) Add VNC server & noVNC web app for debugging and control.
 # COPY ./.devcontainer/scripts/desktop-lite-debian.sh /tmp/scripts/desktop-lite-debian.sh
 # ENV DBUS_SESSION_BUS_ADDRESS="autolaunch:" \
 #   VNC_RESOLUTION="1440x768x16" \
@@ -42,7 +42,7 @@ ENV ROS_DISTRO=$ROS_DISTRO
 
 RUN apt-get update && apt-get install -y \
   ros-${ROS_DISTRO}-ros-core \
-  # (Optional) Add rqt for debugging and control.
+  # (OPTION) Add RQT for debugging and control.
   # ~nros-${ROS_DISTRO}-rqt* \
   python3-rosdep \
   python3-colcon-common-extensions \
@@ -62,17 +62,20 @@ RUN echo "ENV=$HOME/.shrc; export ENV" >> ~/.profile
 RUN echo "exec bash" >> ~/.shrc
 RUN echo "source /opt/ros/$ROS_DISTRO/setup.bash\nsource /code/install/local_setup.bash" >> ~/.bashrc
 
-# (Optional) Uncomment below if using rqt for icons to show up.
+# (OPTION) Uncomment below if using RQT for icons to show up.
 # RUN mkdir ~/.icons && ln -s /usr/share/icons/Tango ~/.icons/hicolor
 
 COPY ./entrypoint.sh /entrypoint.sh
 RUN chmod +x /entrypoint.sh
-# (Optional) Expose rosbridge port & noVNC port respectively.
+# (OPTION) Expose rosbridge port & noVNC port respectively.
 # EXPOSE 9090 6080
 ENTRYPOINT [ \
-  # (Optional) VNC entrypoint
+  # (OPTION) VNC entrypoint
   # "/usr/local/share/desktop-init.sh", \
   # ROS entrypoint
   "/entrypoint.sh" \
   ]
-CMD [ "bash" ]
+
+# (OPTION) Choose between calling roslaunch directly or opening a bash shell.
+# CMD [ "ros2", "launch", "main", "launch.py" ]
+# CMD [ "bash" ]

Dockerfile.dev

@@ -1,9 +1,9 @@
 # syntax=docker/dockerfile:1
 
 # Dockerfile for development
-# Please create a separate Dockerfile with more precise dependencies for production.
+# Below RUN statements are broken up to take advantage of Docker layer cache.
 
-# If developing without a Nvidia GPU, using base Ubuntu 22.04 is possible.
+# (OPTION) Use base Ubuntu 22.04 if a Nvidia GPU is unavailable.
 # FROM ubuntu:22.04
 FROM nvidia/cuda:11.7.1-cudnn8-runtime-ubuntu22.04
 
@@ -12,15 +12,14 @@ ENV LANG="C.UTF-8" LC_ALL="C.UTF-8"
 RUN echo 'Etc/UTC' > /etc/timezone \
   && ln -s /usr/share/zoneinfo/Etc/UTC /etc/localtime
 
-# Below RUN statements are broken up to take advantage of Docker layer cache.
 RUN apt-get update \
   # Needed to curl and authorize ROS repository key.
   && apt-get install -y curl gnupg lsb-release software-properties-common \
   && apt-get install -y sudo git \
   # Enable universe repositories.
   && add-apt-repository universe
 
-# Create user & add to sudoers.
+# Create user and add to sudoers.
 ARG USERNAME=user
 ARG USER_UID=1000
 ARG USER_GID=$USER_UID
@@ -30,7 +29,7 @@ RUN groupadd -g $USER_GID $USERNAME \
   && echo $USERNAME ALL=\(root\) NOPASSWD:ALL > /etc/sudoers.d/$USERNAME \
   && chmod 0440 /etc/sudoers.d/$USERNAME
 
-# Add VNC for debugging and control.
+# Add VNC server & noVNC web app for debugging and control.
 COPY ./.devcontainer/scripts/desktop-lite-debian.sh /tmp/scripts/desktop-lite-debian.sh
 ENV DBUS_SESSION_BUS_ADDRESS="autolaunch:" \
   VNC_RESOLUTION="1440x768x16" \
@@ -40,20 +39,18 @@ ENV DBUS_SESSION_BUS_ADDRESS="autolaunch:" \
   DISPLAY=":1"
 RUN bash /tmp/scripts/desktop-lite-debian.sh $USERNAME password
 
-# Enable openCL support (OpenCV autodetects this & will use it to accelerate).
+# Enable openCL support (OpenCV uses it for hardware acceleration).
 RUN mkdir -p /etc/OpenCL/vendors && \
   echo "libnvidia-opencl.so.1" > /etc/OpenCL/vendors/nvidia.icd
 
-# Curl key & authorize ROS repository.
+# Curl key and authorize ROS repository.
 RUN curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg
 RUN echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(. /etc/os-release && echo $UBUNTU_CODENAME) main" > /etc/apt/sources.list.d/ros2.list
 
 # ROS Humble's support window is till 2027 (correct as of 23 Nov 2022).
 ARG ROS_DISTRO=humble 
 ENV ROS_DISTRO=$ROS_DISTRO
 
-# Upgrading all system packages to latest is optional.
-# RUN apt-get update && apt-get upgrade -y
 RUN apt-get update
 RUN apt-get install -y \
   ros-${ROS_DISTRO}-ros-base \
@@ -64,26 +61,17 @@ RUN apt-get install -y \
 # Set default version of Python to be the one ROS Humble uses.
 RUN update-alternatives --install /usr/bin/python python /usr/bin/python3.10 10
 
-# Initialize rosdep.
+# Initialize rosdep package manager.
 RUN rosdep init && rosdep update
 
-# rqt comes with useful debugging and control tools.
-# rqt's plugin support allows for custom visualizations, tools or control panels.
+# RQT comes with useful debugging and control tools.
+# RQT's plugin support allows for custom visualizations, tools or control panels.
 RUN apt-get install -y ~nros-${ROS_DISTRO}-rqt*
 
-# One of the dependencies breaks Xsession. So we won't use the entire ROS desktop suite.
-# It is better for dependency management anyways to explicitly choose what is installed.
-# See https://github.com/ros2/variants/blob/master/desktop/package.xml
-# and browse https://index.ros.org/ to find out what is in the ROS desktop suite.
-# RUN apt-get install -y ros-${ROS_DISTRO}-desktop
-
-# Install some common dependencies.
-# RUN apt-get install -y python3-opencv ros-${ROS_DISTRO}-rosbridge-suite
-
-# Use Python Black formatter.
+# Use black by default for formatting Python code.
 RUN apt-get install -y black
 
-# Needed for devcontainer hooks to run.
+# Needed for Dev Container lifecycle hooks to run.
 COPY ./.devcontainer /tmp/.devcontainer
 
 COPY ./entrypoint.sh /entrypoint.sh
@@ -100,8 +88,8 @@ USER $USERNAME
 # Make /bin/sh launch bash instead.
 RUN echo "ENV=$HOME/.shrc; export ENV" >> ~/.profile
 RUN echo "exec bash" >> ~/.shrc
-# Auto-activate ROS whenever shell is opened.
+# Auto-activate ROS whenever bash shell is opened.
 RUN echo "source /opt/ros/$ROS_DISTRO/setup.bash\nsource /code/install/local_setup.bash" >> ~/.bashrc
 
-# Ensure rqt icons show up.
+# Ensure RQT icons show up.
 RUN mkdir ~/.icons && ln -s /usr/share/icons/Tango ~/.icons/hicolor