Skip to content

docs: generate the module reference from the type stubs - #407

Merged
bdbarnett merged 5 commits into
mainfrom
stubs-reference
Nov 10, 2026
Merged

bdbarnett merged 5 commits into
mainfrom
stubs-reference

Conversation

@bdbarnett

Copy link
Copy Markdown
Contributor

The Reference section is now written from the type stubs. Each module's names, constructors, options and constants on the Reference pages come from its .pyi, so the docs and your editor's completion can't drift apart. This PR is stacked on #404 (the stubs) and targets its branch; retarget it to main once that merges.

The existing pages keep their file names and headings, so every link to them still works, including the #audiobiquad and #audioroutemidside anchors. Their hand-written module sections are now generated, with the prose that a user needs moved into the stubs' docstrings (the constructor table for the biquad stays as a short hand-written table). Two new pages, Mixing and routing and Analysis and utilities, cover the modules that had no page, and the pump and Vorbis pages gain a generated names section. The docs had never been built with Sphinx here, so this also adds docs/conf.py, a requirements file, .readthedocs.yaml and a Docs workflow that builds with warnings as errors. Making that build pass meant pointing links to folders and files outside docs/ at GitHub and fixing eight heading jumps in the upstream reports.

I built the site with sphinx-build -W --keep-going with and without network and it finishes with no warnings; all 25 modules render. I didn't build it on Read the Docs, and I haven't read every generated page for wording.

@bdbarnett
bdbarnett changed the base branch from stubs-rest to main November 10, 2026 15:29
@bdbarnett
bdbarnett merged commit 654d95c into main Nov 10, 2026
64 of 65 checks passed
@bdbarnett
bdbarnett deleted the stubs-reference branch November 10, 2026 16:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

1 participant