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

[ttypic]

autogenerated API references docs using MkDocs

Summary by CodeRabbit

• New Features

  • Comprehensive API documentation added for REST & Realtime clients, auth, channels, messaging, types, and utilities.
  • Automated CI workflow to build and publish the documentation site.

• Documentation

  • New docs structure, overview, API reference pages, and MkDocs configuration with rendering settings.

• Chores

  • Added optional docs dependencies and updated ignore rules to exclude generated documentation artifacts.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Adds a MkDocs-based documentation site (content, config, and deps), a GitHub Actions workflow to build and publish the site (with AWS role assumption and artifact upload), and updates VCS ignore to exclude generated site/. No public API or code behavior changes.

Changes

Cohort / File(s)	Summary
CI / Docs Workflow ​.github/workflows/docs.yml	New GitHub Actions workflow: checkout (with submodules), setup Python 3.12, cache venv keyed by uv.lock, install deps via uv sync --extra docs, build site with uv run mkdocs build, configure AWS credentials (assume role), and upload site/ using ably/sdk-upload-action@v2. Triggers: workflow_dispatch, pull_request, push to main.
VCS ignore ​.gitignore	Adds site/ to ignore generated docs output.
Docs config & deps mkdocs.yml, pyproject.toml	Adds MkDocs Material configuration, mkdocstrings Python handler and Markdown extensions; adds [project.optional-dependencies].docs with mkdocs, mkdocs-material, and mkdocstrings[python] for Python 3.12+.
Docs content docs/README.md, docs/index.md, docs/api/... docs/api/overview.md, docs/api/rest.md, docs/api/realtime.md, docs/api/auth.md, docs/api/channels.md, docs/api/messages.md, docs/api/types.md, docs/api/util.md	New documentation pages and API reference stubs using mkdocstrings directives and examples. No code or public API changes.

Sequence Diagram(s)

sequenceDiagram
    participant Developer
    participant GH_Actions as GH Actions Runner
    participant PythonEnv as Python 3.12 Env
    participant UV as uv Tool
    participant AWS as AWS STS/IAM
    participant AblyUpload as ably/sdk-upload-action
    Developer->>GH_Actions: Trigger workflow (push/PR/dispatch)
    GH_Actions->>GH_Actions: checkout repo (with submodules)
    GH_Actions->>PythonEnv: setup-python 3.12
    GH_Actions->>UV: install deps (uv sync --extra docs)
    GH_Actions->>PythonEnv: run build (uv run mkdocs build)
    GH_Actions->>AWS: configure-aws-credentials (assume role)
    GH_Actions->>AblyUpload: upload artifact `site/` with assumed creds
    AblyUpload->>AWS: use assumed role credentials to store/upload artifact

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐇 I hopped through branches, stitched pages bright,
MkDocs and mkdocstrings hummed through the night,
site/ sleeps quiet where git won't peep,
Creds passed safely, the artifact to keep,
A rabbit cheers — the docs take flight.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title clearly and specifically summarizes the main change: adding autogenerated API reference documentation using MkDocs, with issue reference AIT-289.
Linked Issues check	✅ Passed	The PR successfully fulfills the linked issue AIT-289 objective to provide updated/autogenerated API reference documentation for the Python SDK, including comprehensive MkDocs setup and documentation files.
Out of Scope Changes check	✅ Passed	All changes are directly related to setting up and documenting API references via MkDocs, with no unrelated modifications beyond the documentation setup scope.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch AIT-289/api-docs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 4

🤖 Fix all issues with AI agents

In `@docs/api/rest.md`:
- Around line 17-59: Update the REST examples to use async/await for async
methods and remove the incorrect ChannelOptions usage: change all calls to
channel.publish(...) and channel.history() to await channel.publish(...) and
history = await channel.history(); remove the import and use of ChannelOptions
(it belongs to Realtime) and instead pass cipher directly to rest.channels.get
by using cipher=CipherParams(...), e.g. channel =
rest.channels.get('encrypted-channel', cipher=cipher_params), keeping the
existing CipherParams import/constructor.

In `@docs/api/types.md`:
- Around line 1-39: Consolidate duplicate type docs by removing TokenDetails and
TokenRequest from docs/api/types.md and adding clear cross-references to their
canonical definitions in docs/api/auth.md (or vice-versa), update
docs/api/types.md to either document the abstract VCDiff interface
ably.types.options.VCDiffDecoder and also mention the concrete implementation
ably.vcdiff.default_vcdiff_decoder.AblyVCDiffDecoder (with a short note
distinguishing interface vs implementation), and normalize the ChannelOptions
entry by either changing ably.realtime.realtime_channel.ChannelOptions to the
ably.types.* pattern or adding an explicit note explaining why ChannelOptions
lives under ably.realtime.realtime_channel to keep documentation consistent.

In `@docs/index.md`:
- Around line 17-18: Update the deprecation sentence in the docs/index.md notice
that currently reads "will be deprecated from November 1, 2025" to reflect that
the date has passed by changing it to a present-tense statement such as "are
deprecated as of November 1, 2025" or "have been deprecated as of November 1,
2025"; locate and edit the exact string "SDK versions < 2.0.0-beta.6 will be
deprecated from November 1, 2025." and replace it with the preferred phrasing.

In `@pyproject.toml`:
- Around line 43-47: The docs dependency constraints in pyproject.toml are too
permissive for mkdocs-material and too restrictive for mkdocstrings; update the
docs list entries so "mkdocs-material>=9.5.32,<10.0.0; python_version>='3.8'"
replaces the current "mkdocs-material>=9.0.0,<10.0.0; python_version>='3.8'" to
exclude vulnerable releases, and change "mkdocstrings[python]>=0.24.0,<1.0.0;
python_version>='3.8'" to "mkdocstrings[python]>=0.24.0,<2.0.0;
python_version>='3.8'" to allow the stable 1.0.0 release (edit the docs = [...]
block in pyproject.toml where these dependency strings appear).

🧹 Nitpick comments (3)

mkdocs.yml (1)

1-6: Consider updating site_url to the actual documentation hosting URL.

The site_url currently points to the GitHub repository, but it should typically point to where the documentation is actually hosted (e.g., https://ably.github.io/ably-python/ if using GitHub Pages). This affects canonical URLs and sitemap generation.

.github/workflows/docs.yml (2)

1-9: Consider adding an explicit workflow name.

The workflow lacks a name property, which makes it harder to identify in the GitHub Actions UI. The first line is a comment but not a workflow name.

Suggested improvement

 # This workflow builds the documentation and creates an artifact
+name: Documentation
 
 on:
   workflow_dispatch:

---

30-35: Consider adding restore-keys for partial cache restoration.

When uv.lock changes, the cache won't be restored at all. Adding restore-keys allows partial cache restoration, which can speed up dependency installation.

Suggested improvement

       - 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') }}
+          restore-keys: |
+            venv-${{ runner.os }}-3.12-

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Jira integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 7c26134 and 89d86e1.

⛔ Files ignored due to path filters (1)

• uv.lock is excluded by !**/*.lock

📒 Files selected for processing (14)

• .github/workflows/docs.yml
• .gitignore
• docs/README.md
• docs/api/auth.md
• docs/api/channels.md
• docs/api/messages.md
• docs/api/overview.md
• docs/api/realtime.md
• docs/api/rest.md
• docs/api/types.md
• docs/api/util.md
• docs/index.md
• mkdocs.yml
• pyproject.toml

🧰 Additional context used

🪛 LanguageTool

docs/index.md

[style] ~16-~16: Using many exclamation marks might seem excessive (in this case: 3 exclamation marks for a text that’s 1600 characters long)
Context: ...ing platforms (Linux, macOS, Windows). !!! important SDK versions < 2.0.0-beta...

(EN_EXCESSIVE_EXCLAMATION)

docs/README.md

[style] ~30-~30: Consider shortening or rephrasing this to strengthen your wording.
Context: ...lly rebuilds the documentation when you make changes to the source files. ## Documentation Str...

(MAKE_CHANGES)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (7)

• GitHub Check: check (3.9)
• GitHub Check: check (3.13)
• GitHub Check: check (3.14)
• GitHub Check: check (3.12)
• GitHub Check: check (3.10)
• GitHub Check: check (3.8)
• GitHub Check: check (3.11)

🔇 Additional comments (13)

.gitignore (1)

60-60: LGTM!

Adding site/ to .gitignore is correct for MkDocs documentation builds.

docs/api/util.md (1)

25-27: No action needed. VCDiffDecoder (in ably.types.options) and AblyVCDiffDecoder (in ably.vcdiff.default_vcdiff_decoder) serve distinct purposes: the former is an abstract base class defining the interface, and the latter is the default concrete implementation that extends it. Both should be documented separately—users need to understand the interface contract and the available implementation.

Likely an incorrect or invalid review comment.

docs/api/realtime.md (1)

1-19: Realtime module paths are correct and verified.

All referenced modules and classes in the documentation exist at the correct locations:

• ably.realtime.realtime.AblyRealtime ✓
• ably.realtime.realtime_channel.Channels ✓
• ably.realtime.realtime_channel.RealtimeChannel ✓
• ably.realtime.connection.Connection ✓

No changes needed.

docs/api/auth.md (1)

10-15: Duplication confirmed: TokenDetails and TokenRequest are documented in both auth.md and types.md.

The autodoc directives for TokenDetails and TokenRequest appear in both files (auth.md lines 11, 15 and types.md lines 19, 23). This duplication mirrors a broader pattern in the documentation where core types are documented in context-specific sections (e.g., Channel/Channels appear in multiple module docs, RealtimeChannel appears twice). Consolidate if this is unintentional, or document the rationale if this contextual approach is by design.

mkdocs.yml (1)

7-77: Well-structured MkDocs configuration.

The configuration follows Material theme best practices with proper light/dark mode support, sensible navigation features, and appropriate mkdocstrings options for Python API documentation. The filter "!^_" correctly excludes private members.

docs/api/rest.md (1)

1-16: REST Client documentation structure is well-organized.

The API reference sections using mkdocstrings directives are properly structured.

docs/index.md (2)

28-52: Clear and functional quick start example.

The async context manager pattern with AblyRealtime is well-demonstrated. The example covers connection, subscription, and publishing effectively.

---

1-69: Well-structured landing page documentation.

The documentation provides a comprehensive introduction with appropriate sections for installation, quick start, features, and support links. The content aligns well with SDK documentation best practices.

docs/api/messages.md (1)

1-37: Comprehensive and accurate message types documentation.

All referenced message types and operations are correctly documented with proper module paths. The coverage of core message functionality, mutable message operations (update, delete, append), and presence messaging is well-structured and complete.

docs/api/channels.md (1)

1-27: Documentation structure and module paths are correct.

All referenced modules and classes exist in the codebase with the correct module paths:

• ably.rest.channel.Channels and ably.rest.channel.Channel in ./ably/rest/channel.py
• ably.realtime.realtime_channel.Channels and ably.realtime.realtime_channel.RealtimeChannel in ./ably/realtime/realtime_channel.py
• ably.realtime.realtimepresence.RealtimePresence in ./ably/realtime/realtimepresence.py

docs/api/overview.md (1)

1-82: LGTM!

The API reference overview is well-structured with clear hierarchy, appropriate navigation links to related documentation pages, and concise descriptions of core clients and components.

docs/README.md (1)

1-52: LGTM!

Clear and comprehensive documentation for building and serving the docs locally. The instructions align well with the CI workflow and explain the mkdocstrings integration effectively.

.github/workflows/docs.yml (1)

37-48: LGTM!

The dependency installation, build, and upload steps are correctly configured and align with the documentation instructions.

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In @.github/workflows/docs.yml:
- Around line 3-9: The workflow currently triggers on pull_request, push and
workflow_dispatch, but the AWS credential configuration and upload steps run for
PRs (causing secret/role failures for forks); update the job or those specific
steps (the AWS credential setup and the S3/upload steps referenced in the PR
comment) to only execute when the event is not a pull_request by adding a
conditional such as if: github.event_name != 'pull_request' (or if:
github.event.pull_request == null) on the steps or job, so AWS secrets are only
used on push/workflow_dispatch events.

♻️ Duplicate comments (2)

pyproject.toml (1)

43-47: Re‑verify docs dependency version bounds (security + compatibility).
Please re-check current advisories and latest stable releases for MkDocs tooling and adjust bounds if needed (e.g., raise minimums for patched versions and consider allowing mkdocstrings 1.x if stable).

Possible update (if verification supports it)

 docs = [
   "mkdocs>=1.5.0,<2.0.0; python_version>='3.8'",
-  "mkdocs-material>=9.0.0,<10.0.0; python_version>='3.8'",
-  "mkdocstrings[python]>=0.24.0,<1.0.0; python_version>='3.8'",
+  "mkdocs-material>=9.5.32,<10.0.0; python_version>='3.8'",
+  "mkdocstrings[python]>=0.24.0,<2.0.0; python_version>='3.8'",
 ]

Please verify via:

latest mkdocs-material security advisories minimum patched version

mkdocstrings python latest stable version 1.x compatibility

docs/index.md (1)

17-18: Update deprecation tense to reflect the past date.
This notice references a date already in the past; tweak the tense to avoid confusion.

Suggested fix

 !!! important
-    SDK versions < 2.0.0-beta.6 will be [deprecated](https://ably.com/docs/platform/deprecate/protocol-v1) from November 1, 2025.
+    SDK versions < 2.0.0-beta.6 are [deprecated](https://ably.com/docs/platform/deprecate/protocol-v1) as of November 1, 2025.

🧹 Nitpick comments (1)

.github/workflows/docs.yml (1)

19-31: Pin GitHub Actions to commit SHAs for supply‑chain hardening.

Using moving tags (@v4, @v5, etc.) allows upstream changes without review. Consider pinning to specific SHAs and updating intentionally.

🔒 Example pattern

-      - uses: actions/checkout@v4
+      - uses: actions/checkout@<pinned-sha> # v4.x.x

Apply the same approach to actions/setup-python, astral-sh/setup-uv, actions/cache, aws-actions/configure-aws-credentials, and ably/sdk-upload-action.

Also applies to: 34-35, 48-55

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Jira integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 89d86e1 and cb2040e.

⛔ Files ignored due to path filters (1)

• uv.lock is excluded by !**/*.lock

📒 Files selected for processing (14)

• .github/workflows/docs.yml
• .gitignore
• docs/README.md
• docs/api/auth.md
• docs/api/channels.md
• docs/api/messages.md
• docs/api/overview.md
• docs/api/realtime.md
• docs/api/rest.md
• docs/api/types.md
• docs/api/util.md
• docs/index.md
• mkdocs.yml
• pyproject.toml

✅ Files skipped from review due to trivial changes (3)

• docs/api/realtime.md
• docs/api/messages.md
• docs/api/rest.md

🚧 Files skipped from review as they are similar to previous changes (5)

• docs/api/auth.md
• docs/api/util.md
• mkdocs.yml
• docs/api/channels.md
• .gitignore

🧰 Additional context used

🪛 LanguageTool

docs/README.md

[style] ~30-~30: Consider shortening or rephrasing this to strengthen your wording.
Context: ...lly rebuilds the documentation when you make changes to the source files. ## Documentation Str...

(MAKE_CHANGES)

docs/index.md

[style] ~16-~16: Using many exclamation marks might seem excessive (in this case: 3 exclamation marks for a text that’s 1600 characters long)
Context: ...ing platforms (Linux, macOS, Windows). !!! important SDK versions < 2.0.0-beta...

(EN_EXCESSIVE_EXCLAMATION)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (8)

• GitHub Check: check (3.14)
• GitHub Check: check (3.11)
• GitHub Check: check (3.12)
• GitHub Check: check (3.8)
• GitHub Check: check (3.13)
• GitHub Check: check (3.10)
• GitHub Check: check (3.9)
• GitHub Check: docs

🔇 Additional comments (4)

docs/api/types.md (1)

1-39: Docs structure looks good for mkdocstrings.

docs/README.md (1)

1-52: Clear setup and usage guidance.

docs/api/overview.md (1)

1-82: Overview reads well and links are coherent.

.github/workflows/docs.yml (1)

41-45: Docs build flow looks good.

uv sync --extra docs followed by uv run mkdocs build is clear and keeps docs deps isolated.

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@docs/api/rest.md`:
- Around line 1-3: Update the REST client documentation header to state the
client provides asynchronous (not synchronous) access; replace the phrase
"synchronous access" with "asynchronous access" and optionally note that major
methods such as publish(), history(), stats(), and other API methods are async
and should be awaited so readers understand the need to use await with these
functions.

♻️ Duplicate comments (1)

.github/workflows/docs.yml (1)

47-59: Skip AWS publish steps on pull requests to avoid failures.

The AWS credentials configuration and upload steps will fail for fork PRs (secrets unavailable) and shouldn't publish unmerged documentation. Add a condition to skip these steps on pull request events.

🛠️ Suggested fix

       - name: Configure AWS Credentials
         uses: aws-actions/configure-aws-credentials@v4
+        if: github.event_name != 'pull_request'
         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
+        if: github.event_name != 'pull_request'
         with:
           sourcePath: site/
           githubToken: ${{ secrets.GITHUB_TOKEN }}
           artifactName: docs

🧹 Nitpick comments (1)

.github/workflows/docs.yml (1)

34-39: Consider using restore-keys for cache fallback.

The cache key is specific to the exact uv.lock hash. Adding restore-keys would allow partial cache hits when dependencies change slightly, improving cache utilization.

💡 Suggested improvement

       - 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') }}
+          restore-keys: |
+            venv-${{ runner.os }}-3.12-

[coderabbitai]

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash

# Find the AblyRest implementation
echo "=== Searching for AblyRest class definition ==="
find . -name "*.py" -type f | xargs grep -l "class AblyRest" | head -5

# Check the rest module structure
echo "=== REST module files ==="
find . -path "*/ably/rest*" -name "*.py" -type f | head -20

Repository: ably/ably-python

Length of output: 836

---

🏁 Script executed:

#!/bin/bash

echo "=== AblyRest class in rest.py ==="
cat -n ./ably/rest/rest.py | head -100

echo ""
echo "=== Checking for async methods in rest.py ==="
rg -n "async def|def " ./ably/rest/rest.py | head -30

Repository: ably/ably-python

Length of output: 5611

---

🏁 Script executed:

#!/bin/bash

echo "=== Checking Channel class methods ==="
rg -n "async def|def " ./ably/rest/channel.py | grep -E "(publish|history)" | head -10

echo ""
echo "=== Full method signatures around publish and history ==="
rg -B 2 "async def (publish|history)" ./ably/rest/channel.py

Repository: ably/ably-python

Length of output: 1240

---

Update documentation to reflect asynchronous access, not synchronous.

Line 3 claims the REST client provides "synchronous access," but the implementation shows all major methods (publish(), history(), stats(), etc.) are async functions requiring await. Update the description to accurately state the client provides asynchronous access.

🤖 Prompt for AI Agents

In `@docs/api/rest.md` around lines 1 - 3, Update the REST client documentation
header to state the client provides asynchronous (not synchronous) access;
replace the phrase "synchronous access" with "asynchronous access" and
optionally note that major methods such as publish(), history(), stats(), and
other API methods are async and should be awaited so readers understand the need
to use await with these functions.

[owenpearson]

some other questions:

• if we're sticking with mkdocs i think we need to at least resolve all the build warnings emitted when building the docs. currently there are a lot
• there's a few weird artefacts in the static website like having no linebreaks or separators between method params:

and some params randomly appear in a collapsable blue box whereas others don't? no idea what the difference is

[owenpearson]

our .tool-version still lists python 3.9, we should change it to a version which can run all the development tasks

[owenpearson]

you have ably.rest.channel.Channels in here twice

[owenpearson]

i have to say, the model for building this seems not ideal? like all we really need to do is say what our public exports are (AblyRest and AblyRealtime). from there a tool like this should be able to walk the public API and skip anything that starts with an underscore. i think having to declare every class in these markdown files is a pain to keep in sync with the source code and inevitably someone will forget to update it when they make a change.