docs: add MkDocs API documentation with versioned GitHub Pages publishing by xinghaohuang91 · Pull Request #77 · twilio/twilio-agent-connect-python

xinghaohuang91 · 2026-07-06T22:32:17Z

Summary

Adds an auto-generated API documentation site for the Python SDK, published to GitHub Pages — the Python equivalent of the TypeDoc setup used by twilio-voice.js.

Generator: MkDocs + Material theme + mkdocstrings (Python handler). API reference is extracted directly from source docstrings and type hints via Griffe — no hand-maintained API docs.
Structure: docs/ with an intro page and one API page per public subpackage (Core, Channels, Context, Tools, Adapters, Conversation Intelligence, Models), each rendering the real public symbols from src/tac.
Versioning: mike publishes each release into its own subfolder with a version-picker dropdown in the header and a latest alias.
Publishing: .github/workflows/docs.yml builds and deploys to the gh-pages branch on every published release (and via manual workflow_dispatch).
Local tooling: make docs (build), make docs-serve (live preview), make docs-versions (list published versions). Added a docs dependency group to pyproject.toml.
Branding: Twilio logo/favicon and indigo palette; README links to the published API Reference.
Contributor guidance: CLAUDE.md documents that docstrings are published documentation — write them in Markdown, keep the mkdocstrings filters list current when changing internal-facing methods, and consult the published reference for the public surface.

Scope note: This is the first docs PR — it stands up the infrastructure and polishes the Core module's docstrings/API page. The other modules (Channels, Context, Tools, Adapters, Conversation Intelligence, Models) still render from their existing docstrings and will be polished in follow-up PRs.

Review feedback addressed

Linked the relevant Twilio product docs directly from the source docstrings (rendered on the API pages): Conversation Memory, Enterprise Knowledge, and Conversation Intelligence.
Renamed the "Intelligence" nav entry/page to "Conversation Intelligence" to match the product name.
Hardened the docs workflow against shell injection: both the Resolve version step and the Deploy step now pass the workflow_dispatch input / resolved version through env: and reference "$VERSION" in the run script, instead of interpolating ${{ }} directly into the shell. This closes the path where a crafted dispatch input could inject commands into a runner holding contents: write + Artifactory OIDC.
Added a Documentation section to CLAUDE.md covering docstring-as-published-docs conventions, keeping the mkdocstrings filters list current, and the published API reference URL.
Removed the stray dev version from the published site so the dropdown shows only released versions (mike sorts non-numeric names above releases, so dev was pinned to the top). The root already redirects to latest.

One-time setup required after merge

Settings → Pages → Source: "Deploy from a branch" → gh-pages / (root).
The workflow_dispatch "Run workflow" button only appears once this workflow is on main.

Type of Change

Documentation update

Checklist

Tests added/updated
Documentation updated
Tested E2E

SDK Parity

This is the Python SDK. If this change affects shared functionality, ensure the TypeScript SDK is updated as well.

Change is Python-specific (no TypeScript update needed)

…ishing Generate API reference from source docstrings/type hints via mkdocstrings, themed with Material. Publish versioned docs to gh-pages with mike (version picker dropdown, latest alias) on release or manual dispatch. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Copilot

Pull request overview

Note

Copilot couldn't run its full agentic review because no GitHub Actions runner was available. Make sure your repository has a runner available to run Copilot's review, or add a copilot-setup-steps.yml file specifying one with the runs-on attribute. See the docs for more details.

Adds auto-generated, versioned API docs for the Python SDK using MkDocs + mkdocstrings, with automated publishing to GitHub Pages on releases.

Changes:

Add a docs optional dependency group for MkDocs tooling.
Introduce MkDocs configuration and API reference pages under docs/.
Add a GitHub Actions workflow and Makefile targets to build/serve/version and deploy docs via mike.

Reviewed changes

Copilot reviewed 12 out of 13 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
pyproject.toml	Adds a `docs` dependency group for MkDocs/mkdocstrings/mike tooling.
mkdocs.yml	Configures MkDocs Material, mkdocstrings, nav structure, and mike versioning.
docs/index.md	Adds the docs homepage with installation and quick start content.
docs/api/*.md	Adds mkdocstrings-powered API reference pages per public subpackage.
Makefile	Adds `docs`, `docs-serve`, and `docs-versions` targets using `uv`.
.github/workflows/docs.yml	Builds and deploys versioned docs to `gh-pages` for releases and manual runs.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

…inks mike creates version aliases as symlinks by default, which GitHub Pages' legacy branch builder rejects ("repository must not contain symlinks"), causing the deployment to fail silently. --alias-type=copy writes real files. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Include README.md via pymdownx.snippets so the docs home stays in sync with the repo README instead of duplicating content. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

ryanrishi · 2026-07-07T02:11:20Z

+tac = TAC(TACConfig(
+    api_key="SK...",
+    api_secret="...",
+    conversation_configuration_id="CF...",


Suggested change

conversation_configuration_id="CF...",

conversation_configuration_id="conv_configuration_xxx",

i change it to just point to our root readme.

ryanrishi · 2026-07-07T17:22:40Z

+      - Context: api/context.md
+      - Tools: api/tools.md
+      - Adapters: api/adapters.md
+      - Intelligence: api/intelligence.md


Does it make sense to call this "Conversation Intelligence"? Also wondering if we should link to https://www.twilio.com/docs/conversations/intelligence

make sense. i update the title in markdown and add the links to the code comment so that we dont need to make many custom changes in the each module markdown file.

ryanrishi · 2026-07-07T17:24:04Z

+
+::: tac.context
+    options:
+      show_submodules: false


Can we have subpages for knowledge, memory, etc.? and ideally link to Twilio docs for memory and knowledge

we actually dont need a subpage, in context, we will have this

and good point, i add memory and knowledge links to the clients.

- Link Conversation Memory, Enterprise Knowledge, and Conversation Intelligence product docs from client/module docstrings - Rename Intelligence nav/page to Conversation Intelligence - Harden docs workflow against shell injection via env vars - Twilio-branded logo, indigo palette, and README API Reference links

ryanrouleau · 2026-07-10T16:25:51Z

-
-        Required for Conversation Orchestrator / Memory / Knowledge:
-        - TWILIO_CONVERSATION_CONFIGURATION_ID: Conversation Orchestrator configuration ID
+        **Required:**


Should we add in Claude.md to use markdown in comments (and that the comments etc. will be picked up docs)?

good point.

ryanrouleau · 2026-07-10T16:29:36Z

+            signature_crossrefs: true
+            merge_init_into_class: true
+            filters:
+              ["!^_", "!^trigger_message_ready$", "!^trigger_interrupt$", "!^trigger_conversation_ended$", "!^register_partner_connector$", "!^is_orchestrator_enabled$"]


Should add a note to claude.md to keep this updated when adding/modifying any internal facing API methods?

Maybe also mentioning in the CLAUDE.md for full public API reference to see the site so claude picks it up automatically for devs using the package

ryanrouleau · 2026-07-10T16:31:50Z

@@ -0,0 +1,73 @@
+name: Docs
+


Is it possible to default to the latest version in the UI?

remove dev version which is only for testing.
so the mike order the dropdown items based on name, non-numeric first then number, so dev show first... I just remove it.

when we have 2.2.0, it should be 2.2.0 -> 2.1.0. it should be good. then.

Note that docstrings render on the MkDocs API reference site, to write them in Markdown, to keep the mkdocstrings filters list current when changing internal-facing methods, and point to the published reference.

The deploy step interpolated steps.version.outputs.version straight into the shell script, so a crafted workflow_dispatch input could inject commands into a runner holding contents: write + Artifactory OIDC. Pass it through env: and reference "$VERSION", matching the Resolve version step.

ryanrouleau

nice! 🚀

Copilot AI review requested due to automatic review settings July 6, 2026 22:32

xinghaohuang91 requested review from ryanrishi and ryanrouleau as code owners July 6, 2026 22:32

semgrep-code-twilio Bot reviewed Jul 6, 2026

View reviewed changes

Comment thread .github/workflows/docs.yml

Copilot AI reviewed Jul 6, 2026

View reviewed changes

Comment thread .github/workflows/docs.yml

xinghaohuang91 and others added 2 commits July 6, 2026 15:48

docs: use root README as the docs homepage

74452c4

Include README.md via pymdownx.snippets so the docs home stays in sync with the repo README instead of duplicating content. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

ryanrishi reviewed Jul 7, 2026

View reviewed changes

ryanrouleau reviewed Jul 10, 2026

View reviewed changes

Comment thread .github/workflows/docs.yml

ryanrouleau reviewed Jul 10, 2026

View reviewed changes

xinghaohuang91 added 2 commits July 10, 2026 09:56

docs: document docstring-as-published-docs conventions in CLAUDE.md

68f2b89

Note that docstrings render on the MkDocs API reference site, to write them in Markdown, to keep the mkdocstrings filters list current when changing internal-facing methods, and point to the published reference.

ryanrouleau approved these changes Jul 10, 2026

View reviewed changes

xinghaohuang91 merged commit 2059ae2 into main Jul 10, 2026
15 checks passed

xinghaohuang91 deleted the docs-mkdocs-setup branch July 10, 2026 17:25

	conversation_configuration_id="CF...",
	conversation_configuration_id="conv_configuration_xxx",

Uh oh!

Conversation

xinghaohuang91 commented Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Review feedback addressed

One-time setup required after merge

Type of Change

Checklist

SDK Parity

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ryanrouleau Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ryanrouleau left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

xinghaohuang91 commented Jul 6, 2026 •

edited

Loading

ryanrouleau Jul 10, 2026 •

edited

Loading