From 340e602cc7ab36e615a8146aab44ef12cd0482e1 Mon Sep 17 00:00:00 2001 From: NuwanJ Date: Fri, 12 Sep 2025 08:13:23 +0530 Subject: [PATCH 1/2] docs: Add initial documentation structure and requirements for the Robot Library --- .github/workflows/docs-cd.yml | 57 +++++++++++++++ README.md | 113 +++++++++++++++++++++++++++--- docs/Makefile | 23 +++++++ docs/_static/.gitkeep | 0 docs/api/index.rst | 13 ++++ docs/api/modules.rst | 7 ++ docs/api/robot.communication.rst | 37 ++++++++++ docs/api/robot.exception.rst | 10 +++ docs/api/robot.helpers.rst | 37 ++++++++++ docs/api/robot.indicators.rst | 29 ++++++++ docs/api/robot.interfaces.rst | 10 +++ docs/api/robot.mqtt.rst | 29 ++++++++ docs/api/robot.rst | 60 ++++++++++++++++ docs/api/robot.sensors.rst | 45 ++++++++++++ docs/api/robot.types.rst | 29 ++++++++ docs/conf.py | 59 ++++++++++++++++ docs/index.md | 18 +++++ docs/installation.md | 29 ++++++++ docs/requirements.txt | 9 +++ docs/usage.md | 115 +++++++++++++++++++++++++++++++ 20 files changed, 721 insertions(+), 8 deletions(-) create mode 100644 .github/workflows/docs-cd.yml create mode 100644 docs/Makefile create mode 100644 docs/_static/.gitkeep create mode 100644 docs/api/index.rst create mode 100644 docs/api/modules.rst create mode 100644 docs/api/robot.communication.rst create mode 100644 docs/api/robot.exception.rst create mode 100644 docs/api/robot.helpers.rst create mode 100644 docs/api/robot.indicators.rst create mode 100644 docs/api/robot.interfaces.rst create mode 100644 docs/api/robot.mqtt.rst create mode 100644 docs/api/robot.rst create mode 100644 docs/api/robot.sensors.rst create mode 100644 docs/api/robot.types.rst create mode 100644 docs/conf.py create mode 100644 docs/index.md create mode 100644 docs/installation.md create mode 100644 docs/requirements.txt create mode 100644 docs/usage.md diff --git a/.github/workflows/docs-cd.yml b/.github/workflows/docs-cd.yml new file mode 100644 index 0000000..f78e8ce --- /dev/null +++ b/.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 diff --git a/README.md b/README.md index bbae27b..0be23ab 100644 --- a/README.md +++ b/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` diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..bdc117f --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,23 @@ +# Minimal Sphinx Makefile + +SPHINXBUILD?=sphinx-build +SOURCEDIR=. +BUILDDIR=_build +PORT?= 9000 + +.PHONY: help clean html apidoc + +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" + +clean: + rm -rf "$(BUILDDIR)" + +apidoc: + sphinx-apidoc -o docs/api src/robot + +html: + $(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" + +livehtml: + sphinx-autobuild --host 0.0.0.0 --port ${PORT} -c . "$(SOURCEDIR)" "$(BUILDDIR)/html" diff --git a/docs/_static/.gitkeep b/docs/_static/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/api/index.rst b/docs/api/index.rst new file mode 100644 index 0000000..ceb171b --- /dev/null +++ b/docs/api/index.rst @@ -0,0 +1,13 @@ +API Reference +============= + +This section is auto-generated from the source code. If you are building locally, run: + +.. code-block:: bash + + sphinx-apidoc -o docs/api src/robot + +.. toctree:: + :maxdepth: 2 + + robot diff --git a/docs/api/modules.rst b/docs/api/modules.rst new file mode 100644 index 0000000..9c1b3af --- /dev/null +++ b/docs/api/modules.rst @@ -0,0 +1,7 @@ +robot +===== + +.. toctree:: + :maxdepth: 4 + + robot diff --git a/docs/api/robot.communication.rst b/docs/api/robot.communication.rst new file mode 100644 index 0000000..f558f3e --- /dev/null +++ b/docs/api/robot.communication.rst @@ -0,0 +1,37 @@ +robot.communication package +=========================== + +Submodules +---------- + +robot.communication.communication module +---------------------------------------- + +.. automodule:: robot.communication.communication + :members: + :show-inheritance: + :undoc-members: + +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: diff --git a/docs/api/robot.exception.rst b/docs/api/robot.exception.rst new file mode 100644 index 0000000..842e054 --- /dev/null +++ b/docs/api/robot.exception.rst @@ -0,0 +1,10 @@ +robot.exception package +======================= + +Module contents +--------------- + +.. automodule:: robot.exception + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/api/robot.helpers.rst b/docs/api/robot.helpers.rst new file mode 100644 index 0000000..a51b3a6 --- /dev/null +++ b/docs/api/robot.helpers.rst @@ -0,0 +1,37 @@ +robot.helpers package +===================== + +Submodules +---------- + +robot.helpers.coordinate module +------------------------------- + +.. automodule:: robot.helpers.coordinate + :members: + :show-inheritance: + :undoc-members: + +robot.helpers.motion\_controller module +--------------------------------------- + +.. automodule:: robot.helpers.motion_controller + :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: diff --git a/docs/api/robot.indicators.rst b/docs/api/robot.indicators.rst new file mode 100644 index 0000000..d00b035 --- /dev/null +++ b/docs/api/robot.indicators.rst @@ -0,0 +1,29 @@ +robot.indicators package +======================== + +Submodules +---------- + +robot.indicators.abstract\_indicator module +------------------------------------------- + +.. automodule:: robot.indicators.abstract_indicator + :members: + :show-inheritance: + :undoc-members: + +robot.indicators.neopixel module +-------------------------------- + +.. automodule:: robot.indicators.neopixel + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: robot.indicators + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/api/robot.interfaces.rst b/docs/api/robot.interfaces.rst new file mode 100644 index 0000000..2fbf4d4 --- /dev/null +++ b/docs/api/robot.interfaces.rst @@ -0,0 +1,10 @@ +robot.interfaces package +======================== + +Module contents +--------------- + +.. automodule:: robot.interfaces + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/api/robot.mqtt.rst b/docs/api/robot.mqtt.rst new file mode 100644 index 0000000..bf9d252 --- /dev/null +++ b/docs/api/robot.mqtt.rst @@ -0,0 +1,29 @@ +robot.mqtt package +================== + +Submodules +---------- + +robot.mqtt.mqtt\_msg module +--------------------------- + +.. automodule:: robot.mqtt.mqtt_msg + :members: + :show-inheritance: + :undoc-members: + +robot.mqtt.robot\_mqtt\_client module +------------------------------------- + +.. automodule:: robot.mqtt.robot_mqtt_client + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: robot.mqtt + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/api/robot.rst b/docs/api/robot.rst new file mode 100644 index 0000000..28d36a0 --- /dev/null +++ b/docs/api/robot.rst @@ -0,0 +1,60 @@ +robot package +============= + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + robot.communication + robot.exception + robot.helpers + robot.indicators + robot.interfaces + robot.mqtt + robot.sensors + robot.types + +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: + +robot.virtual\_robot module +--------------------------- + +.. automodule:: robot.virtual_robot + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: robot + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/api/robot.sensors.rst b/docs/api/robot.sensors.rst new file mode 100644 index 0000000..7ae6661 --- /dev/null +++ b/docs/api/robot.sensors.rst @@ -0,0 +1,45 @@ +robot.sensors package +===================== + +Submodules +---------- + +robot.sensors.abstract\_sensor module +------------------------------------- + +.. automodule:: robot.sensors.abstract_sensor + :members: + :show-inheritance: + :undoc-members: + +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: diff --git a/docs/api/robot.types.rst b/docs/api/robot.types.rst new file mode 100644 index 0000000..45c93dd --- /dev/null +++ b/docs/api/robot.types.rst @@ -0,0 +1,29 @@ +robot.types package +=================== + +Submodules +---------- + +robot.types.proximity\_reading\_type module +------------------------------------------- + +.. automodule:: robot.types.proximity_reading_type + :members: + :show-inheritance: + :undoc-members: + +robot.types.rgb\_color\_type module +----------------------------------- + +.. automodule:: robot.types.rgb_color_type + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: robot.types + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..3c63122 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,59 @@ +from __future__ import annotations + +import os +import sys +from datetime import datetime + +# Add project src to path so autodoc can import modules +ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..")) +SRC = os.path.join(ROOT, "src") +if SRC not in sys.path: + sys.path.insert(0, SRC) + + +project = "Robot Library (Python)" +author = "PeraSwarm" +copyright = f"{datetime.now().year}, {author}" + +extensions = [ + "myst_parser", + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.napoleon", + "sphinx_autodoc_typehints", +] + +autosummary_generate = True +autodoc_default_options = { + "members": True, + "undoc-members": True, + "show-inheritance": True, +} + +napoleon_google_docstring = True +napoleon_numpy_docstring = False + +# If you cannot or do not want to install heavy deps, you can mock them here +# autodoc_mock_imports = ["paho", "paho.mqtt", "paho.mqtt.client"] + +templates_path = ["_templates"] +html_static_path = ["_static"] + +# html_theme = "furo" +html_theme = "sphinx_rtd_theme" +html_theme_options = { + "collapse_navigation": False, + "navigation_depth": 3, + "titles_only": False, + "prev_next_buttons_location": "bottom", + "sticky_navigation": False, + "style_nav_header_background": "#3468af", +} + + +source_suffix = { + ".rst": "restructuredtext", + ".md": "markdown", +} + +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".venv", ".github"] diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..957b2d8 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,18 @@ +--- +title: Robot Library Python +--- + +# Robot Library Documentation + +Welcome to the documentation for the Python robot library. This site includes installation instructions, usage guides, and an auto-generated API reference. + +## Contents + +```{toctree} +:maxdepth: 2 + +README +installation +usage +api/index +``` diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..3f90ca7 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,29 @@ +--- +title: Installation +--- + +# Installation + +Requirements: + +- Python 3.8+ +- `paho-mqtt` (installed automatically when installing the package) + +## Robot Library Installation + +```bash +git clone git@github.com:Pera-Swarm/robot-library-python.git +cd robot-library-python +python -m venv .venv +. .venv/bin/activate # Windows: .venv\\Scripts\\activate +pip install -U pip +pip install -e . +``` + +## Building Docs locally + +```bash +pip install -r docs/requirements.txt +sphinx-apidoc -o docs/api src/robot +python -m sphinx -b html docs docs/_build/html +``` diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..55caf1b --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,9 @@ +furo>=2024.8.6 +Sphinx>=7.2 +myst-parser>=2.0 +sphinx-autodoc-typehints>=2.2 +sphinx-autobuild==2024.8.25 +sphinx_rtd_theme==7.3.1 + +# Ensure imports succeed during autodoc +paho-mqtt>=2.0 diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..2fcb39c --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,115 @@ +--- +title: Usage +--- + +# Usage Guide + +This guide shows how to configure MQTT, build a `VirtualRobot`, use motion control, read sensors, send communications, and control indicators. + +## Configure MQTT + +```python +from robot import MQTTSettings + +MQTTSettings.server = "localhost" +MQTTSettings.port = 1883 +MQTTSettings.user_name = "" +MQTTSettings.password = "" +MQTTSettings.channel = "v1" +``` + +## Subclass `VirtualRobot` + +```python +from robot import VirtualRobot +from robot.interfaces import RobotState + +class MyRobot(VirtualRobot): + def loop(self): + if self.state == RobotState.RUN: + # read sensors, move, and communicate here + self.delay(1000) + +robot = MyRobot(1, 0, 0, 90) +robot.start() +robot.run() +``` + +## Motion Control + +Use `MotionController` directly or through a `Robot` via `self.motion`. + +```python +from robot import MotionController + +motion = MotionController() # standalone with a stub coordinate +motion.move(150, 150, duration=1000) # forward 1 second +motion.rotate_degree(120, 90) # rotate 90 degrees +``` + +In a robot loop: + +```python +self.motion.move(180, 180, duration=500) +self.motion.rotate_degree(160, -45) +``` + +Configure geometry and speeds via `robot.configs.robot_settings.RobotSettings`. + +## Sensors + +Sensors are initialized in `Robot.setup()` and available on the robot instance. + +Distance: + +```python +dist_cm = self.dist_sensor.get_distance() +``` + +Color: + +```python +rgb = self.color_sensor.get_color() # RGBColorType +print(rgb.get_r(), rgb.get_g(), rgb.get_b()) +``` + +Proximity (multi-angle): + +```python +# Optionally configure angles first +self.proximity_sensor.set_angles([0, 45, 90, 135, 180]) +reading = self.proximity_sensor.get_proximity() +print(reading.distances()) +for c in reading.colors(): + print(c.to_string_color()) +``` + +## Communications + +Simple broadcast-like messages: + +```python +self.simple_comm.send_message("hello swarm") +self.simple_comm.send_message_with_distance("tag", distance=10) +``` + +Directed messages (to controller routing topic): + +```python +self.directed_comm.send_message("to leader") +``` + +Override `communication_interrupt(self, msg: str)` in your robot to handle inbound messages. + +## Indicators (NeoPixel) + +```python +self.neo_pixel.change_color(0, 128, 255) +``` + +## Extensibility Guidelines + +- Subclass `VirtualRobot` to add behaviors; implement `loop()` and optionally `sensor_interrupt`/`communication_interrupt`. +- New sensors/indicators: follow `robot.sensors.abstract_sensor` / `robot.indicators.abstract_indicator`. Subscribe to topics in `__init__`, implement `handle_subscription`, and publish using `RobotMqttClient`. +- MQTT is namespaced by `MQTTSettings.channel` (e.g., `v1/robot/create`), mirroring the original Java design. + From 073921680169b9063a63f1b7f5e6e2bee0884f74 Mon Sep 17 00:00:00 2001 From: NuwanJ Date: Fri, 12 Sep 2025 08:19:31 +0530 Subject: [PATCH 2/2] docs: Update Makefile and installation instructions for improved documentation build process --- docs/Makefile | 8 +++++++- docs/api/index.rst | 13 ------------- docs/api/robot.communication.rst | 8 -------- docs/api/robot.exception.rst | 10 ---------- docs/api/robot.helpers.rst | 8 -------- docs/api/robot.indicators.rst | 8 -------- docs/api/robot.interfaces.rst | 10 ---------- docs/api/robot.mqtt.rst | 29 ----------------------------- docs/api/robot.rst | 12 ------------ docs/api/robot.sensors.rst | 8 -------- docs/api/robot.types.rst | 29 ----------------------------- docs/installation.md | 16 ++++++++++++++++ 12 files changed, 23 insertions(+), 136 deletions(-) delete mode 100644 docs/api/index.rst delete mode 100644 docs/api/robot.exception.rst delete mode 100644 docs/api/robot.interfaces.rst delete mode 100644 docs/api/robot.mqtt.rst delete mode 100644 docs/api/robot.types.rst diff --git a/docs/Makefile b/docs/Makefile index bdc117f..b4f7145 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -3,6 +3,8 @@ SPHINXBUILD?=sphinx-build SOURCEDIR=. BUILDDIR=_build +ROOTDIR=.. +PY?=python PORT?= 9000 .PHONY: help clean html apidoc @@ -14,7 +16,11 @@ clean: rm -rf "$(BUILDDIR)" apidoc: - sphinx-apidoc -o docs/api src/robot + @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" diff --git a/docs/api/index.rst b/docs/api/index.rst deleted file mode 100644 index ceb171b..0000000 --- a/docs/api/index.rst +++ /dev/null @@ -1,13 +0,0 @@ -API Reference -============= - -This section is auto-generated from the source code. If you are building locally, run: - -.. code-block:: bash - - sphinx-apidoc -o docs/api src/robot - -.. toctree:: - :maxdepth: 2 - - robot diff --git a/docs/api/robot.communication.rst b/docs/api/robot.communication.rst index f558f3e..e53e76d 100644 --- a/docs/api/robot.communication.rst +++ b/docs/api/robot.communication.rst @@ -4,14 +4,6 @@ robot.communication package Submodules ---------- -robot.communication.communication module ----------------------------------------- - -.. automodule:: robot.communication.communication - :members: - :show-inheritance: - :undoc-members: - robot.communication.directed\_comm module ----------------------------------------- diff --git a/docs/api/robot.exception.rst b/docs/api/robot.exception.rst deleted file mode 100644 index 842e054..0000000 --- a/docs/api/robot.exception.rst +++ /dev/null @@ -1,10 +0,0 @@ -robot.exception package -======================= - -Module contents ---------------- - -.. automodule:: robot.exception - :members: - :show-inheritance: - :undoc-members: diff --git a/docs/api/robot.helpers.rst b/docs/api/robot.helpers.rst index a51b3a6..b84e488 100644 --- a/docs/api/robot.helpers.rst +++ b/docs/api/robot.helpers.rst @@ -12,14 +12,6 @@ robot.helpers.coordinate module :show-inheritance: :undoc-members: -robot.helpers.motion\_controller module ---------------------------------------- - -.. automodule:: robot.helpers.motion_controller - :members: - :show-inheritance: - :undoc-members: - robot.helpers.robot\_mqtt module -------------------------------- diff --git a/docs/api/robot.indicators.rst b/docs/api/robot.indicators.rst index d00b035..3b831c6 100644 --- a/docs/api/robot.indicators.rst +++ b/docs/api/robot.indicators.rst @@ -4,14 +4,6 @@ robot.indicators package Submodules ---------- -robot.indicators.abstract\_indicator module -------------------------------------------- - -.. automodule:: robot.indicators.abstract_indicator - :members: - :show-inheritance: - :undoc-members: - robot.indicators.neopixel module -------------------------------- diff --git a/docs/api/robot.interfaces.rst b/docs/api/robot.interfaces.rst deleted file mode 100644 index 2fbf4d4..0000000 --- a/docs/api/robot.interfaces.rst +++ /dev/null @@ -1,10 +0,0 @@ -robot.interfaces package -======================== - -Module contents ---------------- - -.. automodule:: robot.interfaces - :members: - :show-inheritance: - :undoc-members: diff --git a/docs/api/robot.mqtt.rst b/docs/api/robot.mqtt.rst deleted file mode 100644 index bf9d252..0000000 --- a/docs/api/robot.mqtt.rst +++ /dev/null @@ -1,29 +0,0 @@ -robot.mqtt package -================== - -Submodules ----------- - -robot.mqtt.mqtt\_msg module ---------------------------- - -.. automodule:: robot.mqtt.mqtt_msg - :members: - :show-inheritance: - :undoc-members: - -robot.mqtt.robot\_mqtt\_client module -------------------------------------- - -.. automodule:: robot.mqtt.robot_mqtt_client - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: robot.mqtt - :members: - :show-inheritance: - :undoc-members: diff --git a/docs/api/robot.rst b/docs/api/robot.rst index 28d36a0..547e914 100644 --- a/docs/api/robot.rst +++ b/docs/api/robot.rst @@ -8,13 +8,9 @@ Subpackages :maxdepth: 4 robot.communication - robot.exception robot.helpers robot.indicators - robot.interfaces - robot.mqtt robot.sensors - robot.types Submodules ---------- @@ -43,14 +39,6 @@ robot.robot\_base module :show-inheritance: :undoc-members: -robot.virtual\_robot module ---------------------------- - -.. automodule:: robot.virtual_robot - :members: - :show-inheritance: - :undoc-members: - Module contents --------------- diff --git a/docs/api/robot.sensors.rst b/docs/api/robot.sensors.rst index 7ae6661..9cf6702 100644 --- a/docs/api/robot.sensors.rst +++ b/docs/api/robot.sensors.rst @@ -4,14 +4,6 @@ robot.sensors package Submodules ---------- -robot.sensors.abstract\_sensor module -------------------------------------- - -.. automodule:: robot.sensors.abstract_sensor - :members: - :show-inheritance: - :undoc-members: - robot.sensors.color module -------------------------- diff --git a/docs/api/robot.types.rst b/docs/api/robot.types.rst deleted file mode 100644 index 45c93dd..0000000 --- a/docs/api/robot.types.rst +++ /dev/null @@ -1,29 +0,0 @@ -robot.types package -=================== - -Submodules ----------- - -robot.types.proximity\_reading\_type module -------------------------------------------- - -.. automodule:: robot.types.proximity_reading_type - :members: - :show-inheritance: - :undoc-members: - -robot.types.rgb\_color\_type module ------------------------------------ - -.. automodule:: robot.types.rgb_color_type - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: robot.types - :members: - :show-inheritance: - :undoc-members: diff --git a/docs/installation.md b/docs/installation.md index 3f90ca7..629df15 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -22,8 +22,24 @@ pip install -e . ## Building Docs locally +From the repository root: + ```bash pip install -r docs/requirements.txt sphinx-apidoc -o docs/api src/robot python -m sphinx -b html docs docs/_build/html ``` + +Or from inside the `docs/` directory: + +```bash +pip install -r requirements.txt +make apidoc +make html +``` + +Use the below command to serve the docs with live reload: + +```bash +make livehtml +```