mkdocs (#9)

* try out pydantic's doc workflow

* workflow syntax

* update docs.yml

* add doc extra

* add robot teleop doc

.github/workflows/docs.yml

@@ -3,29 +3,48 @@ on:
   push:
     branches:
       - main
-permissions:
-  contents: write
+      - docs/*
+env:
+  COLUMNS: 150
+
 jobs:
-  deploy:
+  publish:
     runs-on: ubuntu-latest
+    timeout-minutes: 30
+
     steps:
       - uses: actions/checkout@v4
+      - name: checkout gh-pages
+        uses: actions/checkout@v4
         with:
-          fetch-depth: 0
-      - name: Configure Git Credentials
-        run: |
-          git config user.name github-actions[bot]
-          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
-      - uses: actions/setup-python@v5
+          ref: gh-pages
+
+      - uses: actions/setup-python@v4
         with:
-          python-version: 3.12
-      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
-      - uses: actions/cache@v4
+          python-version: '3.12'
+
+      - name: install
+        run: pip install uv
+
+      - name: checkout current branch
+        uses: actions/checkout@v4
+
+      - name: Set git credentials
+        run: |
+          git config --global user.name "${{ github.actor }}"
+          git config --global user.email "${{ github.actor }}@users.noreply.github.com"
+
+      - run: uv run --extra doc mike deploy -b gh-pages dev --push
+        if: github.ref == 'refs/heads/main'
+
+      - if: startsWith(github.ref, 'refs/heads/docs')
+        id: check-version
+        uses: samuelcolvin/[email protected]
         with:
-          key: mkdocs-material-${{ env.cache_id }}
-          path: .cache
-          restore-keys: |
-            mkdocs-material-
-      - run: pip install uv
-      - run: git pull
-      - run: uv run --extra doc mike deploy --push --ignore-remote-status --update-aliases ${{ github.event.release.tag_name }} latest
+          version_file_path: 'src/aact/__about__.py'
+          skip_env_check: true
+
+      - run: uv run --extra doc mike deploy -b gh-pages ${{ steps.check-version.outputs.VERSION }} latest --update-aliases --push
+        if: startsWith(github.ref, 'refs/heads/docs') && !fromJSON(steps.check-version.outputs.IS_PRERELEASE)
+        env:
+          AACT_VERSION: v${{ steps.check-version.outputs.VERSION }}

docs/applications/robot-teleoperation.md

@@ -0,0 +1,64 @@
+# Teleoperating Robots with AAct, Quest, and Stretch
+
+The latency of the AAct system is low enough to allow for teleoperating robots in real-time. This is a powerful capability that can be used for a variety of applications, such as teleoperating a robot to perform a task in a remote location, collecting ego-centric (or together with exocentric) data for training robotics models, or deploying and evaluating models in the real world.
+
+In this demo (live demoed at CoRL 2024), we are going to use Meta Oculus Quest 3 / Pro and Stretch 3 mobile manipulator.
+
+## Prerequisites
+
+### Hardware
+
+- Meta Quest 3 / Pro.
+- Stretch 3 mobile manipulator or Stretch 2R with upgraded webcam.
+
+### Software
+
+- Python 3.10.
+
+## Steps
+
+The overall steps are:
+
+- Launch Stretch control loop.
+- Launch AAct nodes on Stretch.
+- Launch AAct nodes on a local machine.
+- Build and launch app on Meta Quest.
+
+### Launch Stretch control loop
+
+Before running nodes on stretch, please do these:
+
+1. Homing: `python -m teleop.stretch_home`
+2. Running deamon control loop in a tmux or nohup or screen: `python -m teleop.stretch_control_loop`
+
+### Launch AAct nodes on Stretch
+
+You can easily launch the AAct nodes on Stretch by running the following command:
+
+```bash
+aact run-dataflow dataflows/examples/stretch_zmq_streaming.toml
+```
+
+### Launch AAct nodes on a local machine
+
+Before this step, please get the IP of your Oculus Quest. And change line 40 in `dataflows/examples/quest_local_redis.toml` to your IP.
+
+Then, you can launch the AAct nodes on a local machine by running the following command:
+```bash
+aact run-dataflow dataflows/examples/quest_local_redis.toml
+```
+
+### Build and launch app on Meta Quest
+
+We provide the APK file for the app. You can install it on your Meta Quest by running the following command:
+
+```bash
+adb install -r app.apk
+```
+
+But you can also build the app manually, by building the Unity Project.
+
+
+## Demo
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/OChbSQad4ps?si=QQe9MW6Aie_FvRKA" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

mkdocs.yml

@@ -80,6 +80,9 @@ nav:
     - Messages: api/messages.md
   - AAct CLI:
     - Commands: api/cli.md
+- Applications:
+  - Robotics:
+    - Robot Teleoperation: applications/robot-teleoperation.md
 
 plugins:
 - social