Add documentation for client API (#16)

.github/workflows/docs.yml

@@ -0,0 +1,78 @@
+name: Build and Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+      - master
+    paths:
+      - 'docs/**'
+      - 'src/pi_pianoteq/**/*.py'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    branches:
+      - main
+      - master
+    paths:
+      - 'docs/**'
+      - 'src/pi_pianoteq/**/*.py'
+      - '.github/workflows/docs.yml'
+  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 code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Install documentation dependencies
+        run: |
+          pip install -r docs/requirements.txt
+
+      - name: Build documentation
+        run: |
+          sphinx-build -b html docs/source docs/build/html --keep-going
+
+      # Upload as regular artifact for PRs (downloadable)
+      - name: Upload documentation artifact
+        if: github.event_name == 'pull_request'
+        uses: actions/upload-artifact@v4
+        with:
+          name: documentation-preview
+          path: docs/build/html
+          retention-days: 7
+
+      # Upload as pages artifact for deployment (pushes to main/master only)
+      - name: Upload Pages artifact
+        if: github.event_name == 'push'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: 'docs/build/html'
+
+  deploy:
+    # Only deploy on pushes to main/master, not on PRs
+    if: github.event_name == 'push'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -16,6 +16,9 @@ build/
 pi_pianoteq.service
 pi-pianoteq.service
 
+# Sphinx documentation build output
+docs/build/
+
 pi-pianoteq/*
 backup-*/
 htmlcov/

README.md

@@ -2,6 +2,8 @@
 
 Pi-Pianoteq is a Python/MIDI remote control for Pianoteq on Raspberry Pi.
 
+**📚 [Developer Documentation](https://tlsim.github.io/pi-pianoteq/)** - Complete API docs for creating custom clients
+
 ## About
 
 Pi-Pianoteq provides a simplified hardware interface for controlling Pianoteq on a Raspberry Pi 4B using the [Pimoroni GFX HAT](https://github.com/pimoroni/gfx-hat) - a HAT with 128x64 LCD display, 6 touch buttons and RGB backlight. After configuration, you can run Pianoteq without needing a monitor, using the GFX HAT as your interface.
@@ -141,6 +143,21 @@ For developers who want to build and deploy to a remote Pi, see [docs/developmen
 
 ## Documentation
 
+### For Developers
+
+Want to create a custom client for pi-pianoteq? (e.g., web interface, OLED display, rotary encoders, touchscreen, mobile app)
+
+**📚 [Complete Developer Documentation](https://tlsim.github.io/pi-pianoteq/)**
+
+The online documentation includes:
+- **Client Development Guide** - Step-by-step guide to creating custom clients
+- **Architecture Overview** - System design and patterns
+- **API Reference** - Complete ClientApi documentation with examples
+- **Minimal Example Client** - Working reference implementation
+- **Testing Guide** - How to test your custom client
+
+### For Users
+
 - [docs/systemd.md](docs/systemd.md) - Running as a systemd service
 - [docs/development.md](docs/development.md) - Development and deployment workflow
 - [docs/pianoteq-api.md](docs/pianoteq-api.md) - Pianoteq JSON-RPC API reference

docs/requirements.txt

@@ -0,0 +1,4 @@
+sphinx>=8.0
+sphinx-rtd-theme>=3.0
+myst-parser>=4.0
+toml>=0.10