API docs parity: Python

[edburns]

Python API Docs

Parent epic: #1653

Doc format: Docstrings (reStructuredText or Google/NumPy style) processed by Sphinx or pdoc. Type hints in source also serve as documentation.

Culture: Strong convention to write docstrings. PyPI does not require a docs build to publish, but the community expects it. help() in the REPL reads docstrings directly.

Hosting analogues:

Service	How it works
Read the Docs	De facto standard host — builds Sphinx/MkDocs on push; free for OSS. Closest cultural equivalent to javadoc.io
pdoc	Zero-config generator from docstrings
PyPI project page	Renders the long description (usually README), not full API docs

Key difference from Java: No bundled doc artifact in the wheel/sdist. Docs are a separate CI deliverable, typically hosted on Read the Docs.

[edburns]

Requested @brettcannon self-assign. Teams link.

[brettcannon]

Are there plans to publish the docs to RtD?

And I've never even heard of pdoc, so it might be a bit esoteric depending on what the actual goal is here (e.g. to publish docs to a site or just make sure everything has docstrings).

[edburns]

@brettcannon

Are there plans to publish the docs to RtD?

And I've never even heard of pdoc, so it might be a bit esoteric depending on what the actual goal is here (e.g. to publish docs to a site or just make sure everything has docstrings).

As the Python SME, you have the charter to define what is the best to implement the goal of the parent Epic #1653 .

Briefly, I want a value in the Python row for the API Docs cell:

Available SDKs

SDK	Location	Cookbook	Installation	API docs
Node.js / TypeScript	nodejs/	Cookbook	npm install @github/copilot-sdk
Python	python/	Cookbook	pip install github-copilot-sdk
Go	go/	Cookbook	go get github.com/github/copilot-sdk/go	API docs
.NET	dotnet/	Cookbook	dotnet add package GitHub.Copilot.SDK
Rust	rust/	—	cargo add github-copilot-sdk	API docs
Java	java/	Cookbook	Maven coordinates com.github:copilot-sdk-java See instructions for Maven and Gradle	API docs

If RtD is the accepted practice of the Python community, then please go with that.

[brettcannon]

@edburns the problem is Read the Docs requires an account, so someone is going to need to own that. I think MS used to have a paid account, but I don't know the status of it (I'll go find out).

[brettcannon]

This is on hold until how the docs will be hosted is decided. Regardless, it looks like is will be on GitHub infrastructure and not a 3rd party site like RtD to keep it easier to maintain.