Add API docs GH page and README updates

[cretz]

🚀 What

Need API docs hosted on GH pages (we did some sphinx hacking to get it right). We chose to publish on each main merge instead of each release.

Also updated README with pypi badge and adjust pyproject.toml to include Python version classifiers so we can add that pypi+pyversion badge after next release.

💻 How

Sphinx doc gen and publish on main merge. Also some README and pyproject updates.

🔬 Testing

Had workflow run as part of this PR before reverting that trigger. Can see docs at https://basetenlabs.github.io/baseten-python/.

[Copilot]

Pull request overview

Adds automated API documentation generation and publishing to GitHub Pages, along with minor packaging/readme metadata updates to better surface docs and PyPI status.

Changes:

• Introduces a scripts.docgen module that builds pydoctor HTML docs into _site/ for GitHub Pages publishing.
• Adds a GitHub Actions workflow to generate and deploy the docs site.
• Updates project metadata (Python version classifiers, dev dependency) and README (PyPI badge + API docs link), and ignores _site/.

Reviewed changes

Copilot reviewed 4 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
uv.lock	Locks new dev/doc tooling dependencies (pydoctor and transitive deps).
scripts/docgen/__main__.py	Implements pydoctor-based doc generation into _site/api with a root redirect.
README.md	Adds PyPI badge and links to hosted API docs.
pyproject.toml	Adds Python version classifiers, adds pydoctor to dev deps, and adds poe task for doc generation.
.gitignore	Ignores _site build output.
.github/workflows/docs.yml	Builds and deploys _site to GitHub Pages on main updates (per workflow intent).

---

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

[marius-baseten]

I checked this link. Two thoughts here:

• I never liked mintlify much because of really weak capabilities to display generated lib docs well. I fiddled quite a bit around with it to get something close for chains, specifically, like https://docs.baseten.co/reference/sdk/chains (it sphinx with markdown output and "adatpation" for mintlify mdx... 🤦 ). But liking it or not, I have mixed feelings about "splicing" docs to a totally different location and format. Is there any discussion e.g. with @pat-baseten about this on what our overall strategy is?
• These docs don't look very nice. RTD theme is what I'm used to see for many "nice" python docs, any chanc we can use this here?

[cretz]

I never liked mintlify much because of really weak capabilities to display generated lib docs well

I am not looking for general purpose docs, those will be at docs.baseten.co one day, I need pure API docs and not too concerned with the details of the API docs but we can move them if needed. Definitely don't want Sphinx/RTD style for just the types.

https://docs.baseten.co/reference/sdk/chains

This is exactly what I was trying to avoid, the Sphinx/RTD-style docs that are more prose than API reference and leave a lot to be desired for those looking for quick API reference (not to be confused with actual usage docs which we do not want to mash into the API docs here since most are generated). Notice how you can't even see the things at a glance, it's mashed into one page, space is wasted by English content and whitespace, etc? That lib's API surface is probably about tenth of the size of these docs and is less navigable.

There are dozens and dozens of classes in this doc. I just need some javadoc/rustdoc API style docs that properly link across and without the prose part expected to accompany RTD stuff. That's why I have pydoctor and hosted them at api/ knowing that actual docs will never be here.

If the pure API doc reference as seen here is not acceptable, I can remove this PR if I must, but definitely not looking to make/host full Sphinx/RTD-style API documentation just to see the entire auto-generated Python API at a glance (e.g. https://basetenlabs.github.io/baseten-python/api/baseten.client.managementapi.ApiClient.html similar to https://pkg.go.dev/github.com/basetenlabs/baseten-go@main/client/managementapi).

For comparison to other similarly-OpenAPI-generated docs, can see Anthropic doesn't even document each method/type (see https://platform.claude.com/docs/en/api/sdks/python) and OpenAI just dumped into a single markdown (https://github.com/openai/openai-python/blob/main/api.md). Neither would have put these in Sphinx for this generated surface, yet both still make it hard to see all types.

[cretz]

Ok, I put in the extra time here to get the Sphinx docs to look API-docs-ish (e.g. class per page, left nav trimming, etc) and so I switched over to Sphinx. Not sure I want to do much more here since most of the things are generated code.

Can review at https://basetenlabs.github.io/baseten-python/