[AIT-289] docs: add autogenerated API references docs

.github/workflows/docs.yml

@@ -0,0 +1,59 @@
+# This workflow builds the documentation and creates an artifact
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  docs:
+    runs-on: ubuntu-22.04
+    permissions:
+      deployments: write
+      id-token: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: 'recursive'
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        id: setup-python
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - uses: actions/cache@v4
+        name: Define a cache for the virtual environment based on the dependencies lock file
+        id: cache
+        with:
+          path: ./.venv
+          key: venv-${{ runner.os }}-3.12-${{ hashFiles('uv.lock') }}
+
+      - name: Install dependencies
+        run: uv sync --extra docs
+
+      - name: Build documentation
+        run: uv run mkdocs build
+
+      - name: Configure AWS Credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-region: eu-west-2
+          role-to-assume: arn:aws:iam::${{ secrets.ABLY_AWS_ACCOUNT_ID_SDK }}:role/ably-sdk-builds-ably-python
+          role-session-name: "${{ github.run_id }}-${{ github.run_number }}"
+
+      - name: Upload Documentation
+        uses: ably/sdk-upload-action@v2
+        with:
+          sourcePath: site/
+          githubToken: ${{ secrets.GITHUB_TOKEN }}
+          artifactName: docs

.gitignore

@@ -57,3 +57,4 @@ test/ably/restsetup.py.orig
 .idea/**/*
 ably/sync/**
 test/ably/sync/**
+site/

docs/README.md

@@ -0,0 +1,52 @@
+# Documentation
+
+This directory contains the source files for the Ably Python SDK documentation, built using [MkDocs](https://www.mkdocs.org/) and [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/).
+
+## Building the Documentation
+
+### Prerequisites
+
+- Python 3.8 or higher (documentation tools require Python 3.8+)
+- Install documentation dependencies: `uv sync --extra docs`
+
+### Build HTML Documentation
+
+```bash
+# Build the documentation
+uv run mkdocs build
+
+# The generated HTML will be in the site/ directory
+```
+
+### Serve Documentation Locally
+
+```bash
+# Start a local development server
+uv run mkdocs serve
+
+# Open http://127.0.0.1:8000/ in your browser
+```
+
+The development server automatically rebuilds the documentation when you make changes to the source files.
+
+## Documentation Structure
+
+- `docs/` - Documentation source files (Markdown)
+  - `index.md` - Home page
+  - `api/` - API reference documentation
+- `mkdocs.yml` - MkDocs configuration
+- `site/` - Generated HTML documentation (gitignored)
+
+## How It Works
+
+The documentation uses [mkdocstrings](https://mkdocstrings.github.io/) to automatically generate API documentation from Python docstrings. The special `:::` syntax in Markdown files tells mkdocstrings to extract and render documentation from Python modules:
+
+```markdown
+::: ably.rest.rest.AblyRest
+```
+
+This automatically generates formatted documentation including:
+- Class and method signatures
+- Docstrings
+- Type hints
+- Parameters and return types

docs/api/auth.md

@@ -0,0 +1,19 @@
+# Authentication
+
+The Auth class handles authentication with Ably, supporting API keys, tokens, and token generation.
+
+## Auth
+
+::: ably.rest.auth.Auth
+
+## Token Details
+
+::: ably.types.tokendetails.TokenDetails
+
+## Token Request
+
+::: ably.types.tokenrequest.TokenRequest
+
+## Capability
+
+::: ably.types.capability.Capability

docs/api/channels.md

@@ -0,0 +1,27 @@
+# Channels
+
+Channels provide the interface for publishing and subscribing to messages in Ably.
+
+## REST Channels
+
+### Channels Collection
+
+::: ably.rest.channel.Channels
+
+### REST Channel
+
+::: ably.rest.channel.Channel
+
+## Realtime Channels
+
+### Channels Collection
+
+::: ably.realtime.realtime_channel.Channels
+
+### Realtime Channel
+
+::: ably.realtime.realtime_channel.RealtimeChannel
+
+## Presence
+
+::: ably.realtime.realtimepresence.RealtimePresence

docs/api/messages.md

@@ -0,0 +1,37 @@
+# Messages
+
+Message types represent the data sent through Ably channels.
+
+## Message
+
+The core message type for pub/sub messaging.
+
+::: ably.types.message.Message
+
+## Message Operations
+
+Support for mutable messages (update, delete, append operations).
+
+### MessageVersion
+
+::: ably.types.message.MessageVersion
+
+### MessageAction
+
+::: ably.types.message.MessageAction
+
+### MessageOperation
+
+::: ably.types.operations.MessageOperation
+
+### PublishResult
+
+::: ably.types.operations.PublishResult
+
+### UpdateDeleteResult
+
+::: ably.types.operations.UpdateDeleteResult
+
+## Presence Message
+
+::: ably.types.presence.PresenceMessage

docs/api/overview.md

@@ -0,0 +1,82 @@
+# API Reference Overview
+
+The Ably Python SDK provides two main client interfaces:
+
+## Core Clients
+
+### [REST Client](rest.md)
+
+The REST client (`AblyRest`) provides synchronous access to Ably's REST API:
+
+- Publish messages to channels
+- Query message history
+- Manage channel lifecycle
+- Retrieve statistics
+- Token authentication
+
+Use the REST client when you need simple request/response operations without maintaining a persistent connection.
+
+### [Realtime Client](realtime.md)
+
+The Realtime client (`AblyRealtime`) maintains a persistent connection to Ably:
+
+- Subscribe to channels and receive messages in real-time
+- Publish messages
+- Monitor connection state
+- Track presence
+- Receive live updates
+
+Use the Realtime client for applications that need live updates and bidirectional communication.
+
+## Key Components
+
+### [Authentication](auth.md)
+
+The `Auth` class handles authentication with Ably, supporting:
+
+- API key authentication
+- Token authentication
+- Token generation and renewal
+
+### [Channels](channels.md)
+
+Channel interfaces provide access to messaging functionality:
+
+- REST channels for publishing and history
+- Realtime channels for subscribing to messages
+- Channel state management
+
+### [Messages](messages.md)
+
+Message types represent the data sent through Ably:
+
+- `Message` - Standard pub/sub messages
+- `PresenceMessage` - Presence state changes
+- Encoding and encryption support
+
+### [Types](types.md)
+
+Core data types and configuration:
+
+- `ClientOptions` - Client configuration
+- `TokenDetails` - Authentication tokens
+- `Stats` - Usage statistics
+- Channel and connection options
+
+### [Utilities](util.md)
+
+Utility functions and helpers:
+
+- Exception types
+- Encoding/decoding utilities
+- Cryptographic functions
+
+## Client Capabilities
+
+Both clients share common capabilities:
+
+- **Auto-reconnection**: Automatic connection recovery
+- **Message queueing**: Queues messages during disconnection
+- **Type safety**: Full type hints for IDE support
+- **Async/await support**: Native async support in Realtime client
+- **Error handling**: Comprehensive error types

docs/api/realtime.md

@@ -0,0 +1,19 @@
+# Realtime Client
+
+The Realtime client maintains a persistent connection to Ably, enabling you to subscribe to channels and receive messages in real-time.
+
+## AblyRealtime
+
+::: ably.realtime.realtime.AblyRealtime
+
+## Realtime Channels
+
+::: ably.realtime.realtime_channel.Channels
+
+## Realtime Channel
+
+::: ably.realtime.realtime_channel.RealtimeChannel
+
+## Connection
+
+::: ably.realtime.connection.Connection

docs/api/rest.md

@@ -0,0 +1,59 @@
+# REST Client
+
+The REST client provides synchronous access to Ably's REST API for publishing messages, querying history, and managing channels.
+
+## AblyRest
+
+::: ably.rest.rest.AblyRest
+
+## REST Channels
+
+::: ably.rest.channel.Channels
+
+## REST Channel
+
+::: ably.rest.channel.Channel
+
+## Examples
+
+### Basic Usage
+
+```python
+from ably import AblyRest
+
+# Initialize the REST client
+rest = AblyRest('your-api-key')
+
+# Get a channel
+channel = rest.channels.get('test-channel')
+
+# Publish a message
+channel.publish('event-name', {'key': 'value'})
+
+# Get channel history
+history = channel.history()
+for message in history.items:
+    print(f'Message: {message.data}')
+```
+
+### Publishing Multiple Messages
+
+```python
+# Publish multiple messages at once
+channel.publish([
+    {'name': 'event-1', 'data': 'first message'},
+    {'name': 'event-2', 'data': 'second message'},
+])
+```
+
+### Using Channel Options
+
+```python
+from ably.types.options import ChannelOptions
+from ably.util.crypto import CipherParams
+
+# Get a channel with encryption
+cipher_params = CipherParams(secret_key='your-secret-key')
+options = ChannelOptions(cipher=cipher_params)
+channel = rest.channels.get('encrypted-channel', options)
+```