purdue-arc · jcrm1 · Sep 16, 2022 · Oct 2, 2022 · Oct 8, 2022 · Oct 8, 2022
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,40 @@
+name: Docs
+on:
+  workflow_call:
+    inputs:
+      tag:
+        default: "latest"
+        required: false
+        type: string
+permissions:
+    contents: write
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    env:
+      DOCKER_CMD: >-
+        . /opt/ros/noetic/setup.zsh &&
+        cd catkin_ws &&
+        catkin build --no-status --force-color &&
+        . devel/setup.zsh &&
+        cd src/rocket_league/docs &&
+        pip install -r requirements.txt &&
+        make html -j4
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          path: src/rocket_league
+      - name: Build the local Docker image
+        run: ./src/rocket_league/docker/docker-build.sh --build-arg TAG=${{ inputs.tag }}
+      - name: Build docs
+        run: ./src/rocket_league/docker/docker-run.sh
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.event_name == 'push' }}
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: src/rocket_league/docs/_build/html
+          cname: rktl.purduearc.com
+          force_orphan: true
diff --git a/.github/workflows/top-push.yml b/.github/workflows/top-push.yml
@@ -32,3 +32,8 @@ jobs:
     needs: docker
     if: always()
     uses: purdue-arc/rocket_league/.github/workflows/catkin-build-test.yml@main
+  docs:
+    name: Build and deploy documentation
+    needs: docker
+    if: always()
+    uses: purdue-arc/rocket_league/.github/workflows/docs.yml@main
diff --git a/.gitignore b/.gitignore
@@ -70,6 +70,11 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/html/
+docs/autoapi
+docs/rosdoc/
+docs/rktl_*/
+~!docs/rktl_*/index.md
 
 # PyBuilder
 target/
@@ -145,3 +150,7 @@ dmypy.json
 
 # macOS
 .DS_Store
+
+# docker files
+/docker/.vscode-server
+/docker/.zsh_history
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2020, Purdue ARC
+Copyright (c) 2023, Autonomous Robotics Club of Purdue (Purdue ARC)
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

diff --git a/README.md b/README.md
@@ -1,11 +1,9 @@
 # Rocket League
-This repo contains all the files necessary for the [Rocket League project](https://wiki.purduearc.com/wiki/rocket-league/overview).
+This repo contains all the files necessary for the [Rocket League project](https://www.purduearc.com/wiki/active-projects/rocket-league/).
 This project aims to recreate the video game of the same name via a team of
 autonomously controlled RC cars competing against human controlled ones.
 
-The repo is broken down into several ROS packages, closely matching the system outline:
-
-![System outline](https://wiki.purduearc.com/wiki/rocket-league/assets/images/system-overview.png)
+The repo is broken down into several ROS packages.
 
 ### rktl_autonomy
 This package contains all code for the "High Level Planner" section. It provides

diff --git a/docker/Dockerfile b/docker/Dockerfile
@@ -25,9 +25,10 @@ RUN apt update && \
     ros-$ROS_DISTRO-camera-calibration \
     ros-$ROS_DISTRO-joy \
     ros-$ROS_DISTRO-rosserial-arduino \
-    ros-$ROS_DISTRO-rosbridge-server && \
+    ros-$ROS_DISTRO-rosbridge-server \
+    ros-$ROS_DISTRO-rosdoc-lite && \
     # pip
-    pip3 install pybullet gym[box2d] stable-baselines3 pfilter optuna && \
+    pip3 install pybullet gym[box2d] stable-baselines3 pfilter optuna websockets && \
     # clean up
     rm -rf /var/lib/apt/lists/* /root/.cache/pip/
 

diff --git a/docker/Dockerfile.local b/docker/Dockerfile.local
@@ -15,4 +15,6 @@ RUN usermod -l $USER -u $UID -aG video,dialout -md /home/$USER $BASE_USER && \
     echo "$USER:$PW" | chpasswd
 
 USER $USER
+ENV PATH="${PATH}:/home/$USER/.local/bin"
+
 WORKDIR /home/$USER
diff --git a/docker/README.md b/docker/README.md
@@ -1,6 +1,7 @@
 # Docker Development Image Setup Guide
 
 ## You have to read this
+
 - Run `docker-build.sh` to build the development image.
 - Run `docker-run.sh` to start the container.
 - Run `docker-server-run.sh` to start the container when running on a remote computer connected via `ssh -Y`.
@@ -12,6 +13,7 @@
 ## You don't have to read this
 
 ### Remote Image
+
 `Dockerfile` is used to build `purduearc/rocket-league:latest`.
 [DockerHub](https://hub.docker.com/repository/docker/purduearc/rocket-league/)
 is set up to automatically build this image when changes are made to the `main`
@@ -23,12 +25,14 @@ include any code from this repository or install any ROS dependencies other than
 those found in the standard `ros-melodic-desktop-full` install.
 
 ### Local Image
+
 `Dockerfile.local` is used to build `purduearc/rocket-league:local`. DockerHub
 will not automatically build this image, you have to do that yourself by running
 `docker-build.sh`. Running this will add your user so files can be accessed and
 modified from both the container and your bare-metal computer.
 
 ### Running the image
+
 Run `docker-run.sh` to start the image (`purduearc/rocket-league:local`) and
 mount your local catkin workspace. You can pass in additional arguments directly
 to the `docker run` command. For example, if you have an Nvidia GPU and have
@@ -49,6 +53,7 @@ For example:
   peripherals
 
   ### Server Xauth voodoo explanation
+
   - Remove the old temporary xauth folder
   - Create the temporary xauth folder
   - Copy the current Xauthority file to temp directory to not pollute the main Xauthority file
@@ -58,6 +63,7 @@ For example:
   - Set the display variable for inside the container to use the new display location
 
 ### Other things
+
 You can also run `docker-join.sh` to attach a shell to the container. You can
 pass in arbitrary arguments similar to `docker-run.sh`.
 

diff --git a/docker/docker-build-base.sh b/docker/docker-build-base.sh
@@ -3,7 +3,7 @@
 DOCKER_DIR=$(realpath $(dirname $0))
 REPO_NAME="purduearc/rocket-league"
 
-docker buildx build \
+docker build \
     --tag $REPO_NAME \
     --cache-from=type=registry,ref=${REPO_NAME}:cache \
     $@ \

diff --git a/docker/docker-build.sh b/docker/docker-build.sh
@@ -2,12 +2,14 @@
 
 DOCKER_DIR=$(realpath $(dirname $0))
 REPO_NAME="purduearc/rocket-league"
+M1_ARGS=$([ $(uname -p) == 'arm' ] && echo "--platform linux/arm64/v8")
 
 docker build --build-arg USER=$USER \
              --build-arg PW="robot" \
              --build-arg UID=$(id -u) \
              --build-arg GID=$(id -g) \
              --build-arg ROS_DEPS="$ROS_DEPS" \
+             $M1_ARGS \
              -t $REPO_NAME:local-$USER \
              -f $DOCKER_DIR/Dockerfile.local \
              $@ \

diff --git a/docker/docker-run.sh b/docker/docker-run.sh
@@ -3,23 +3,41 @@
 WS_DIR=$(realpath $(dirname $0)/../../../)
 REPO_NAME="purduearc/rocket-league"
 CONTAINER_NAME="${CONTAINER_NAME:-$USER-arc-rocket-league-dev}"
+MY_DISPLAY=$([ $(uname -s) == 'Darwin' ] && echo "host.docker.internal:0" || echo "$DISPLAY")
+XAUTHORITY="$HOME/.Xauthority"
+echo "Using display $MY_DISPLAY"
+echo "Using $XAUTHORITY as Xauthority"
 echo "mounting host directory $WS_DIR as container directory /home/$USER/catkin_ws"
 
 # tty-specific options
-if [ -t 0 -a -t 1 ]
-then
-    TTY_OPTS="-it"
+if [ -t 0 -a -t 1 ]; then
+    XTRA_OPTS="-it"
+fi
+
+# gitconfig
+if [[ -f "$HOME/.gitconfig" ]]; then
+    XTRA_OPTS="$XTRA_OPTS -v $HOME/.gitconfig:/home/$USER/.gitconfig:ro"
+fi
+
+# Create histroy file and vscode-server files if they don't exist
+if [[ ! -f "$WS_DIR/.zsh_history" ]]; then
+    touch "$WS_DIR/.zsh_history"
+fi
+
+if [[ ! -d "$WS_DIR/.vscode-server" ]]; then
+    mkdir "$WS_DIR/.vscode-server"
 fi
 
 docker run --rm \
-    $TTY_OPTS \
+    $XTRA_OPTS \
     -e USER \
-    -e DISPLAY \
+    -e DISPLAY=$MY_DISPLAY \
     -e NVIDIA_DRIVER_CAPABILITIES=all \
     -v $XAUTHORITY:/home/$USER/.Xauthority:ro \
     -v $WS_DIR:/home/$USER/catkin_ws \
     -v /tmp/.X11-unix:/tmp/.X11-unix \
-    `[ -f ~/.gitconfig ] && echo "-v $HOME/.gitconfig:/home/$USER/.gitconfig:ro"` \
+    -v $WS_DIR/.zsh_history:/home/$USER/.zsh_history \
+    -v $WS_DIR/.vscode-server:/home/$USER/.vscode-server \
     -v ~/.ssh:/home/$USER/.ssh:ro \
     --name $CONTAINER_NAME \
     $@ \

diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,53 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= ~/.local/bin/sphinx-build
+SOURCEDIR     := .
+BUILDDIR      := _build
+
+# All Local Rocket League Packages
+RKTLPKGS := $(wildcard ../rktl_*/)
+
+# Gather all READMES from the project
+READMES := $(foreach readme,$(shell find $(RKTLPKGS) -name 'README.md'),$(subst ../,,$(readme)))
+
+# rosdoc output folder
+ROSDOC_DIR := rosdoc
+ROSDOC_PACKS := $(shell rospack list-names)
+ROSDOC_OUT := $(foreach pack,$(ROSDOC_PACKS),$(ROSDOC_DIR)/$(pack))
+ROSDOC_LOCAL := $(filter $(ROSDOC_DIR)/rktl_%,$(ROSDOC_OUT))
+ROSDOC_HTML_DIRS := action msg srv
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(SPHINXOPTS)
+
+.PHONY: help clean readmes rosdoc Makefile $(READMES) $(ROSDOC_LOCAL)
+
+clean:
+	@$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(SPHINXOPTS)
+	@rm -rf autoapi $(foreach readme,$(READMES),$(dir $(readme))) $(ROSDOC_OUT)
+
+$(READMES):
+	@mkdir -p $(dir $@)
+	@cp ../$@ $@
+
+readmes: $(READMES)
+
+$(ROSDOC_OUT):
+	@mkdir -p $@
+	rosdoc_lite -o $@ $(shell rospack find $(notdir $@)) > /dev/null 2>&1
+	@# Clean up big unnecessary files 
+	@rm $@/html/index.html
+	@rm $@/html/*.png
+	@rm $@/html/*.js
+
+rosdoc: $(ROSDOC_OUT)
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile readmes rosdoc
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(SPHINXOPTS)
diff --git a/docs/_static/favicons/android-chrome-192x192.png b/docs/_static/favicons/android-chrome-192x192.png
diff --git a/docs/_static/favicons/android-chrome-512x512.png b/docs/_static/favicons/android-chrome-512x512.png
diff --git a/docs/_static/favicons/apple-touch-icon.png b/docs/_static/favicons/apple-touch-icon.png
diff --git a/docs/_static/favicons/favicon-16x16.png b/docs/_static/favicons/favicon-16x16.png
diff --git a/docs/_static/favicons/favicon-32x32.png b/docs/_static/favicons/favicon-32x32.png
diff --git a/docs/_static/favicons/favicon.ico b/docs/_static/favicons/favicon.ico
diff --git a/docs/conf.py b/docs/conf.py
@@ -0,0 +1,105 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+
+import os
+import sys
+import shutil
+sys.path.insert(0, os.path.abspath(".."))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "Purdue ARC—Rocket League IRL"
+copyright = "2023, Autonomous Robotics Club of Purdue (Purdue ARC)"
+author = "Autonomous Robotics Club of Purdue (Purdue ARC)"
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+
+extensions = [
+    "sphinx.ext.duration",
+    "sphinx.ext.doctest",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
+    "autoapi.extension",
+    "myst_parser",
+    "sphinx_favicon",
+]
+
+myst_enable_extensions = [
+    "dollarmath",
+    "amsmath",
+    "smartquotes",
+]
+
+autoapi_dirs = [
+    "../rktl_autonomy/src",
+    "../rktl_perception/src",
+    "../rktl_planner/src",
+    "../rktl_sim/src",
+]
+autoapi_keep_files = True
+# autoapi_file_patterns = ["*.py", "*"]
+# autoapi_ignore = ["*.pyc", "*.cpp"]
+
+intersphinx_mapping = {
+    "rtd": ("https://docs.readthedocs.io/en/stable/", None),
+    "python": ("https://docs.python.org/3/", None),
+    "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
+}
+intersphinx_disabled_domains = ["std"]
+
+templates_path = ["_templates"]
+
+# -- Options for EPUB output
+epub_show_urls = "footnote"
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+html_extra_path = ["rosdoc"]
+html_logo = "images/arc_logo.svg"
+
+favicons = [
+    {"href": "favicons/favicon.ico"},
+    {"href": "favicons/favicon-16x16.png"},
+    {"href": "favicons/favicon-32x32.png"},
+    {
+        "rel": "apple-touch-icon",
+        "href": "favicons/apple-touch-icon.png",
+    },
+    {
+        "rel": "android-chrome",
+        "href": "favicons/android-chrome-192x192.png",
+    },
+    {
+        "rel": "android-chrome",
+        "href": "favicons/android-chrome-512-512.png",
+    },
+]