docs: add generated Python API reference

.github/workflows/docs.yml

@@ -0,0 +1,30 @@
+name: Python API reference
+
+on:
+  push:
+    branches: ["master"]
+  pull_request:
+    branches: ["master"]
+  workflow_dispatch:
+
+jobs:
+  docs:
+    name: Build Python API reference
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: "3.12"
+      - name: Install SDK and documentation tools
+        run: python -m pip install -e . -r docs/requirements.txt pytest pytest-asyncio
+      - name: Build API reference
+        run: scripts/build_api_docs.sh
+      - name: Check public API pages
+        run: pytest tests/docs/test_api_docs.py -v
+      - name: Upload API reference
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-api-reference
+          path: docs/api/
+          if-no-files-found: error

.gitignore

@@ -0,0 +1 @@
+/docs/api/

README.md

@@ -74,6 +74,8 @@ See [Coding agent prompts](https://www.assemblyai.com/docs/coding-agent-prompts)
 
 Visit our [AssemblyAI API Documentation](https://www.assemblyai.com/docs) to get an overview of our models!
 
+Build the [Python SDK API reference](docs/README.md) to browse the public classes and methods.
+
 # Quick Start
 
 ## Installation

docs/README.md

@@ -0,0 +1,14 @@
+# Python SDK API reference
+
+The API reference uses public module docstrings and type annotations.
+
+Use Python 3.12 to build the reference. Create and activate a virtual environment. Then install the SDK and the documentation tool:
+
+```bash
+python3.12 -m venv /tmp/assemblyai-sdk-docs
+source /tmp/assemblyai-sdk-docs/bin/activate
+python -m pip install -e . -r docs/requirements.txt
+scripts/build_api_docs.sh
+```
+
+The script writes the HTML files to `docs/api/`.

docs/requirements.txt

@@ -0,0 +1 @@
+pdoc==16.0.0

scripts/build_api_docs.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+export PYTHONWARNINGS=error
+
+pdoc -o docs/api \
+  assemblyai \
+  assemblyai.prerecorded.v2 \
+  assemblyai.sync.v1 \
+  assemblyai.dictation.v1 \
+  assemblyai.llm_gateway.v1

tests/docs/test_api_docs.py

@@ -0,0 +1,31 @@
+from pathlib import Path
+
+API_DOCS = Path(__file__).parents[2] / "docs" / "api"
+
+
+def test_reference_contains_public_sdk_apis():
+    html_files = list(API_DOCS.rglob("*.html"))
+    assert html_files, "Build the API reference before running this test"
+
+    reference = "\n".join(path.read_text(encoding="utf-8") for path in html_files)
+
+    for public_name in (
+        "Transcriber",
+        "SyncTranscriber",
+        "DictationTranscriber",
+        "LLMGateway",
+        "RealTimeTranscriber",
+    ):
+        assert public_name in reference
+
+    for public_member in (
+        "Transcriber.transcribe",
+        "SyncTranscriber.transcribe",
+        "DictationTranscriber.transcribe_live",
+        "LLMGateway.chat",
+        "RealTimeTranscriber.stream",
+    ):
+        assert f'id="{public_member}"' in reference
+
+    assert "assemblyai._audio" not in reference
+    assert "_audio.html" not in reference