Merge pull request #169 from purdue-arc/new-docs

Overhaul documentation

Author: dgerblick

.github/workflows/docs.yml

@@ -0,0 +1,36 @@
+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/src/rocket_league/docs &&
+        pip install -r requirements.txt &&
+        make html
+    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
+          force_orphan: true

.github/workflows/top-push.yml

@@ -32,3 +32,7 @@ jobs:
     needs: docker
     if: always()
     uses: purdue-arc/rocket_league/.github/workflows/catkin-build-test.yml@main
+  docs:
+    name: Build and deploy documentation
+    if: always()
+    uses: purdue-arc/rocket_league/.github/workflows/docs.yml@main

.gitignore

@@ -70,6 +70,10 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/html/
+docs/autoapi
+docs/rosdoc/
+docs/rktl_*/
 
 # PyBuilder
 target/
@@ -145,3 +149,7 @@ dmypy.json
 
 # macOS
 .DS_Store
+
+# docker files
+/docker/.vscode-server
+/docker/.zsh_history

docker/Dockerfile

@@ -25,7 +25,8 @@ 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 && \
     # clean up

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

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 \
     $@ \

docker/docker-run.sh

@@ -8,20 +8,34 @@ echo "Using display $MY_DISPLAY"
 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=$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 \
     $@ \

docs/Makefile

@@ -0,0 +1,52 @@
+# 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/*.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)

docs/conf.py

@@ -0,0 +1,79 @@
+# 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",
+]
+
+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"]

docs/index.md

@@ -0,0 +1,15 @@
+```{include} ../README.md
+```
+
+```{note}
+This project is under active development.
+```
+
+```{toctree}
+:caption: Contents
+:maxdepth: 2
+
+Home <self>
+packages
+autoapi/index
+```