Demonstrate generated SDK API reference on GitHub Pages

[hey-august]

Description

This PR pilots an API technical reference for the Python Server SDK. On every versioned release, the tech ref will automatically generate from source code docstrings and publish to a GitHub Pages site.

Live preview

The live preview is deployed from a fork on my personal GitHub account (hey-august/signalwire-python). On that fork, I merged this branch to main, enabled GitHub Pages, and ran the publish workflow.

Note

This PR description covers the "What" and "How" of this effort. For the "Why", refer to my proposal issue: signalwire/cloud-product#19415

Merge impact

This PR only adds a new reference/ directory (described below in Generator tooling) and a single publish workflow that only runs when invoked manually, or on intentional pushes to the pilot branch (docs/api-reference-pilot). Nothing else is touched, and all generated output is gitignored.

This PR is designed as a careful, self-contained demonstration that can easily be merged and reverted with no impact to the rest of the repository.

Additions

Generator tooling

The generator setup is entirely contained in a new reference/ directory. MkDocs Material and mkdocstrings turn the signalwire package's docstrings into HTML. A build script injects a navbar on top, reusing compiled CSS directly from the SignalWire docs site for 1:1 style match, and generates a landing page that links into each package and out to the guides.

Publish workflow

A new workflow (reference-docs.yml) builds the site and publishes a versioned copy to a gh-pages branch via mike. After merging this PR and enabling GH Pages, it will serve at signalwire.github.io/signalwire-python. Later, we can move this to a custom domain, like reference.signalwire.com/server/python - this is discussed in the proposal.

In the production implementation (currently commented out), the workflow triggers on a v* release tag. Each new release would then regenerate the reference and deploy it as a new version on the same site, with latest updated automatically, so the published docs always match the released code.

Maintainer action needed

After merge, we'll need to turn on GitHub Pages and set its source to the gh-pages branch. GitHub Actions will need write access (it should already have it) so mike can publish to Pages.

All new files live under reference/, except for one workflow (.github/workflows/reference-docs.yml) for the build and publish actions.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Code cleanup / refactor

Related Issues

• Proposal: https://github.com/signalwire/cloud-product/issues/19415
• Fork: https://github.com/hey-august/signalwire-python

Testing

• Added/updated unit tests
• Tested manually
• Tested with live SignalWire credentials (if applicable)

Checklist

• I have read the CONTRIBUTING guidelines
• My code follows the project's style guidelines
• I have added tests for my changes (if applicable)
• I have updated documentation (if applicable)
• All existing tests pass

[hey-august]

Discussed with @niravcodes and @Devon-White. We all agree that new GitHub releases (which trigger package manager updates) should be the trigger for doc regeneration. The workflow in the PR already works this way.

We should determine if versioning will be initially required - none of the Server SDKs have multiple major versions yet, and some languages are totally unversioned.

If we scale this approach to the Browser SDK, we will need to consider whether to include v2 and v3. If they should be included, we will need to know if they are considered officially deprecated or if future updates are a possibility:

• Fully deprecated: easy one-time import
• Updates planned: expanded workflows to pull docs from multiple source code repos

[jpsantosbh]

Should this be changed to main ?

[hey-august]

Thanks for catching this! Just pushed and switched it from the pilot branch to the v* tag trigger. That way we get regenerated docs on a version bump instead of on all pushes to main.

The workflow can still be dispatched manually, though.

[jpsantosbh]

Looks good, left one comment for confirmation only