Add initial documentation structure and requirements for the Robot Library

.github/workflows/docs-cd.yml

@@ -0,0 +1,57 @@
+name: 'Documentation: Publish'
+
+on:
+  push:
+    branches: ['dev']
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+          pip install -r docs/requirements.txt
+
+      - name: Generate API stubs
+        run: |
+          sphinx-apidoc -o docs/api src/robot
+
+      - name: Build HTML
+        run: |
+          python -m sphinx -b html docs docs/_build/html
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build/html
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

README.md

@@ -1,18 +1,115 @@
-# Robot Library Python
+# Robot Library (Python)
 
-A modular Python library for building robot applications. It provides components
-for motion control, sensor access, communication, and indicators.
+A modular Python library for building robot applications. It provides components for motion control, sensors, communications, and indicators over MQTT.
+
+Documentation: the full site is auto-built and deployed to GitHub Pages on pushes to the `dev` branch. Once enabled in the repo settings, it will be available at: `https://pera-swarm.github.io/robot-library-python/`.
 
 ## Installation
 
-```bash
-pip install -e .
+You can install in a few ways:
+
+- Editable (development) install from a local checkout:
+
+  ```bash
+  pip install -e .
+  ```
+
+- From source via Git (replace org/repo as appropriate):
+
+This library requires `paho-mqtt` (declared in `pyproject.toml`) and Python 3.8+.
+
+## Quick Start
+
+Create a virtual robot by subclassing `robot.VirtualRobot`, configure MQTT, and start the main loop:
+
+```python
+from robot import MQTTSettings, VirtualRobot
+from robot.interfaces import RobotState
+
+
+class MyRobot(VirtualRobot):
+    def loop(self):
+        if self.state == RobotState.RUN:
+            print("running...")
+            # do work
+            self.delay(1000)
+
+
+# Configure MQTT broker connection
+MQTTSettings.server = "localhost"
+MQTTSettings.port = 1883
+MQTTSettings.user_name = ""
+MQTTSettings.password = ""
+MQTTSettings.channel = "v1"
+
+r = MyRobot(1, 0, 0, 90)
+r.start()
+r.run()  # or run in a separate thread
+```
+
+See `examples/my_test_robot.py` for a complete runnable example.
+
+## Core Concepts
+
+- Robot: base lifecycle (`start/stop/reset/delay/loop`) and MQTT subscription handling. See `robot.Robot`.
+- VirtualRobot: convenient virtual implementation; subclass and implement `loop`. See `robot.VirtualRobot`.
+- Motion: differential drive style controller for movement and rotation. See `robot.MotionController`.
+- Sensors: distance, color, and proximity, with non-blocking MQTT updates and blocking request/reply helpers.
+- Communication: simple and directed messaging channels to other robots or a controller.
+- Indicators: NeoPixel control via MQTT topics.
+
+## Usage Examples
+
+Motion control:
+
+```python
+from robot import MotionController
+
+motion = MotionController()  # standalone stub coordinate for quick tests
+motion.move(100, 100, duration=1000)   # forward 1s
+motion.rotate_degree(120, 90)          # rotate 90 degrees at speed 120
+```
+
+Sensors (within a `Robot` subclass after `setup()` has run):
+
+```python
+dist = self.dist_sensor.get_distance()
+rgb  = self.color_sensor.get_color()          # RGBColorType
+prox = self.proximity_sensor.get_proximity()  # ProximityReadingType
+```
+
+Communications:
+
+```python
+self.simple_comm.send_message("hello swarm")
+self.directed_comm.send_message_with_distance("to leader", distance=25)
 ```
 
-## Usage
+Indicators:
 
 ```python
-from robot.motion import MotionController
+self.neo_pixel.change_color(255, 128, 0)
+```
+
+## Extending and Customizing
+
+- New behavior: subclass `VirtualRobot` and implement `loop`. Optionally override `sensor_interrupt` or `communication_interrupt`.
+- New sensors/indicators: follow the pattern in `robot.sensors.*` and `robot.indicators.*`, implementing `handle_subscription` and publishing/consuming your desired topics via `RobotMqttClient`.
+- Motion tuning: adjust `robot.configs.robot_settings.RobotSettings` constants (speed bounds, robot geometry) to match your platform.
+- MQTT setup: set fields on `robot.configs.mqtt_settings.MQTTSettings` before constructing robots.
 
-controller = MotionController()
+## Documentation
+
+Sphinx documentation lives in `docs/` and is auto-generated on pushes to `dev` via GitHub Actions, then deployed to GitHub Pages. To build locally:
+
+```bash
+pip install -r docs/requirements.txt
+sphinx-apidoc -o docs/api src/robot
+python -m sphinx -b html docs docs/_build/html
+open docs/_build/html/index.html
 ```
+
+## Contributing
+
+- Run lint and tests: `flake8 src tests` and `PYTHONPATH=src pytest`
+- Example to run: `python examples/my_test_robot.py`

docs/Makefile

@@ -0,0 +1,29 @@
+# Minimal Sphinx Makefile
+
+SPHINXBUILD?=sphinx-build
+SOURCEDIR=.
+BUILDDIR=_build
+ROOTDIR=..
+PY?=python
+PORT?= 9000
+
+.PHONY: help clean html apidoc
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)"
+
+clean:
+	rm -rf "$(BUILDDIR)"
+
+apidoc:
+	@if command -v sphinx-apidoc >/dev/null 2>&1; then \
+		sphinx-apidoc -o api $(ROOTDIR)/src/robot; \
+	else \
+		$(PY) -m sphinx.ext.apidoc -o api $(ROOTDIR)/src/robot; \
+	fi
+
+html:
+	$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html"
+
+livehtml:
+	sphinx-autobuild  --host 0.0.0.0 --port ${PORT} -c . "$(SOURCEDIR)" "$(BUILDDIR)/html"

docs/api/modules.rst

@@ -0,0 +1,7 @@
+robot
+=====
+
+.. toctree::
+   :maxdepth: 4
+
+   robot

docs/api/robot.communication.rst

@@ -0,0 +1,29 @@
+robot.communication package
+===========================
+
+Submodules
+----------
+
+robot.communication.directed\_comm module
+-----------------------------------------
+
+.. automodule:: robot.communication.directed_comm
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+robot.communication.simple\_comm module
+---------------------------------------
+
+.. automodule:: robot.communication.simple_comm
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+Module contents
+---------------
+
+.. automodule:: robot.communication
+   :members:
+   :show-inheritance:
+   :undoc-members:

docs/api/robot.helpers.rst

@@ -0,0 +1,29 @@
+robot.helpers package
+=====================
+
+Submodules
+----------
+
+robot.helpers.coordinate module
+-------------------------------
+
+.. automodule:: robot.helpers.coordinate
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+robot.helpers.robot\_mqtt module
+--------------------------------
+
+.. automodule:: robot.helpers.robot_mqtt
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+Module contents
+---------------
+
+.. automodule:: robot.helpers
+   :members:
+   :show-inheritance:
+   :undoc-members:

docs/api/robot.indicators.rst

@@ -0,0 +1,21 @@
+robot.indicators package
+========================
+
+Submodules
+----------
+
+robot.indicators.neopixel module
+--------------------------------
+
+.. automodule:: robot.indicators.neopixel
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+Module contents
+---------------
+
+.. automodule:: robot.indicators
+   :members:
+   :show-inheritance:
+   :undoc-members:

docs/api/robot.rst

@@ -0,0 +1,48 @@
+robot package
+=============
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   robot.communication
+   robot.helpers
+   robot.indicators
+   robot.sensors
+
+Submodules
+----------
+
+robot.motion module
+-------------------
+
+.. automodule:: robot.motion
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+robot.mqtt\_client module
+-------------------------
+
+.. automodule:: robot.mqtt_client
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+robot.robot\_base module
+------------------------
+
+.. automodule:: robot.robot_base
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+Module contents
+---------------
+
+.. automodule:: robot
+   :members:
+   :show-inheritance:
+   :undoc-members:

docs/api/robot.sensors.rst

@@ -0,0 +1,37 @@
+robot.sensors package
+=====================
+
+Submodules
+----------
+
+robot.sensors.color module
+--------------------------
+
+.. automodule:: robot.sensors.color
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+robot.sensors.distance module
+-----------------------------
+
+.. automodule:: robot.sensors.distance
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+robot.sensors.proximity module
+------------------------------
+
+.. automodule:: robot.sensors.proximity
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+Module contents
+---------------
+
+.. automodule:: robot.sensors
+   :members:
+   :show-inheritance:
+   :undoc-members: