Auto-generate API reference site with pdoc and publish via GitHub Pages - #14
Merged
Conversation
Add a CI/CD pipeline that renders the full API reference from source docstrings and publishes it to GitHub Pages. - scripts/gen_docs.py: builds the pdoc site. It walks the package and passes pdoc an explicit module list because pdoc's auto-discovery honours __all__, which lists API names rather than submodules; without this only the top-level page would render. - .github/workflows/docs.yml: builds the docs on every push and PR, and deploys to GitHub Pages from main via the official Pages actions. - pyproject.toml: add a "docs" extra (pdoc) and include it in dev. - docs/api-reference.md: how to build locally and the one-time steps to enable Pages; linked from the README and docs index. - Fill in docstrings on the public API (Machine route wrappers, model dataclasses and their from_raw, CLI commands) so the generated pages are complete. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012C5JXr99B8vLSXgXc55XaB
Coverage report✅ Total coverage: 100.00% (0.00% vs base |
mullinmax
marked this pull request as ready for review
July 16, 2026 19:48
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds CI/CD that auto-generates the full API reference (every public module, class, method, and function) from the source docstrings and publishes it as a static pdoc website on GitHub Pages.
Once Pages is enabled it will live at
https://warped-pinball.github.io/python-library/and rebuild on every push tomain.What's included
scripts/gen_docs.py— builds the pdoc site. It walks thewarpedpinballpackage and passes pdoc an explicit module list. This is necessary because pdoc's automatic submodule discovery honours a package's__all__, and ours lists the public API names (connect,Machine, the exception classes, …) rather than submodule names — so a barepdoc warpedpinballrenders only the top-level page and skipsmachine,models,cli, the transports, etc. The script picks up new modules automatically..github/workflows/docs.yml— builds the docs on every push and pull request (so broken docs are caught) and deploys to GitHub Pages frommainonly, using the officialupload-pages-artifact/deploy-pagesactions with OIDC.pyproject.toml— newdocsoptional-dependency extra (pdoc>=14), also folded intodev.Machineroute wrappers, themodelsdataclasses and theirfrom_rawclassmethods, and theclisubcommand functions, so the generated pages are complete.docs/api-reference.md— how to build the site locally and the one-time steps to enable Pages; linked from the README and the docs index.Enabling GitHub Pages (one time, needs a repo admin)
The workflow is committed and ready; Pages just needs to be turned on:
main(or run the Docs workflow manually) — thedeployjob publishes the site.Full details and notes (permissions, private-repo caveats, custom domains) are in
docs/api-reference.md.Build & test
python scripts/gen_docs.pybuilds all 10 modules into 11 HTML pages with 0 warnings.ruff check .passes; the existing test suite passes unchanged.Test plan
ruff check .python -m pytestpython scripts/gen_docs.py --output site(clean build, spot-checked rendered docstrings)🤖 Generated with Claude Code
https://claude.ai/code/session_012C5JXr99B8vLSXgXc55XaB
Generated by Claude Code