Add auto-generated API documentation and GitHub Pages deployment#1448
Merged
Add auto-generated API documentation and GitHub Pages deployment#1448
Conversation
- Add mkdocs-material + mkdocstrings for auto-generated API docs - Add docs pages: index, getting-started, API reference (client, models, exceptions, constants) - Add GitHub Actions workflow for deploying to GitHub Pages - Add docs dependency group to pyproject.toml - Add docs/docs-serve Makefile targets - Update Documentation URL to GitHub Pages - Add site/ to .gitignore
liudger
added
documentation
- Replace long code example with concise quick-start - Add link to full documentation on GitHub Pages - Add documentation badge - Update Makefile targets table with docs commands
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1448 +/- ##
=======================================
Coverage 99.89% 99.89%
=======================================
Files 6 6
Lines 955 955
Branches 128 128
=======================================
Hits 954 954
Partials 1 1 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Contributor
There was a problem hiding this comment.
Pull request overview
This PR introduces a MkDocs-based documentation system for python-bsblan, including API reference generation via mkdocstrings and automated GitHub Pages deployment, plus local build/serve Makefile targets.
Changes:
- Added MkDocs configuration (Material theme) and documentation pages, including mkdocstrings-driven API reference.
- Added a GitHub Actions workflow to build and deploy docs to GitHub Pages on pushes to
main. - Added a
docsdependency group plus Makefile targets for building/serving docs locally.
Reviewed changes
Copilot reviewed 11 out of 12 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| pyproject.toml | Adds docs dependency group and updates the project Documentation URL. |
| mkdocs.yml | Configures MkDocs Material, navigation, mkdocstrings, and markdown extensions. |
| docs/index.md | Adds landing page with overview and quick example. |
| docs/getting-started.md | Adds installation/configuration/usage guide and examples. |
| docs/api/client.md | Adds mkdocstrings API reference page for the client and config classes. |
| docs/api/models.md | Adds mkdocstrings API reference page for exported models/types. |
| docs/api/exceptions.md | Adds mkdocstrings API reference page for exceptions. |
| docs/api/constants.md | Adds mkdocstrings API reference page for constants/helpers. |
| Makefile | Adds docs and docs-serve targets. |
| .gitignore | Ignores MkDocs site/ build output. |
| .github/workflows/docs.yaml | Adds CI workflow to build and deploy documentation to GitHub Pages. |
The set_hot_water method takes a SetHotWaterParam dataclass, not keyword arguments. Updated all examples in docs, copilot-instructions, and skill files to use the correct calling convention.
|
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 subscribe to this conversation on GitHub.
Already have an account?
Sign in.
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.
This pull request adds a full documentation system to the project, including automated building and deployment of docs to GitHub Pages, as well as new Makefile targets and project dependencies for documentation. It introduces a comprehensive MkDocs configuration with Material theme, API reference pages using mkdocstrings, and user guides. The documentation can now be built and served locally, and is automatically published on pushes to
main.Documentation system and automation:
.github/workflows/docs.yamlGitHub Actions workflow to build documentation with MkDocs and deploy it to GitHub Pages on every push tomain.mkdocs.ymlconfiguration using the Material theme, navigation, plugins (includingmkdocstringsfor API docs), and markdown extensions.pyproject.tomlto adddocsextra dependencies for documentation building (mkdocs-material,mkdocstrings).Makefile improvements:
docsanddocs-servetargets to theMakefilefor building and serving documentation locally. [1] [2]Documentation content:
docs/:index.md: Project overview and navigation.getting-started.md: Installation, configuration, and usage examples.api/client.md,api/models.md,api/exceptions.md,api/constants.md: API reference generated via mkdocstrings. [1] [2] [3] [4]