Open
Conversation
This commit adds proper documentation generation for the client APIs, enabling developers to create custom clients for pi-pianoteq. Documentation Structure: - Sphinx-based documentation with Read the Docs theme - Auto-generated API reference from docstrings - Comprehensive developer guides with examples - GitHub Pages deployment via GitHub Actions Key Components: 1. Documentation Content: - Client Development Guide - Complete guide to implementing custom clients - Architecture Overview - System design and data flow - Testing Guide - Unit and integration testing strategies - API Reference - Full ClientApi and data model documentation - Minimal Example Client - Working reference implementation 2. Improved Docstrings: - ClientApi: Added detailed docstrings for all 14 methods - Client: Enhanced base class documentation - Instrument: Added class and method docstrings - Following Google style for consistency 3. Build Infrastructure: - Sphinx configuration with autodoc, napoleon, myst-parser - GitHub Actions workflow for automated builds - Deployment to GitHub Pages on main branch - Added Sphinx dependencies to Pipfile dev-packages 4. Documentation Features: - Two-phase initialization explained thoroughly - Complete API method reference with examples - Common patterns and best practices - Thread safety guidelines - Data model documentation (Instrument, Preset) - Troubleshooting and debugging tips 5. Integration: - Updated README with prominent links to online docs - Separate sections for developers and users - .gitignore updated to exclude docs/build/ The documentation will be available at: https://tlsim.github.io/pi-pianoteq/ Addresses #16
The test CI was failing with 'pipenv install --dev --deploy' because Pipfile.lock was out of sync with the added Sphinx dependencies. Solution: - Moved Sphinx dependencies from Pipfile to docs/requirements.txt - Updated docs workflow to use pip install -r docs/requirements.txt - This keeps test workflow unchanged and avoids Pipfile.lock conflicts The docs workflow no longer depends on pipenv, making it simpler and more reliable.
tlsim
force-pushed
the
claude/proper-generated-pianoteq-011CV4atMms1ZYEZq4QGsv6Z
branch
from
f728e02 to
3f26e43
Compare
The docs workflow now builds on pull requests and uploads the built documentation as a downloadable artifact. Changes: - Trigger on pull_request events to master/main - Upload as regular artifact on PRs (downloadable for 7 days) - Upload as Pages artifact only on pushes (for deployment) - Deploy job only runs on pushes, not PRs Usage: 1. Open PR with doc changes 2. Go to Actions tab in the PR 3. Click on the 'Build and Deploy Documentation' workflow run 4. Download 'documentation-preview' artifact 5. Extract and open index.html locally to preview
Fixes for successful documentation build in CI: 1. Created _static and _templates directories - Added .gitkeep files to track empty directories - Fixes 'html_static_path entry does not exist' warning 2. Fixed RST title formatting - Extended underlines/overlines to match title length - Fixed in: client.rst, data-models.rst, architecture.rst - Fixes 'Title overline too short' warnings 3. Added autodoc mock imports - Mock rtmidi, gfxhat, prompt_toolkit, PIL - Allows autodoc to import modules without dependencies - Fixes ModuleNotFoundError warnings 4. Fixed duplicate object descriptions - Added :no-index: to autodoc directives in reference.rst - Prevents duplication with detailed docs in client.rst/data-models.rst - Fixes 'duplicate object description' warnings 5. Suppressed known warnings - Added suppress_warnings for myst.xref_missing - Silences missing cross-reference warnings in existing markdown 6. Removed -W flag from build command - Build now succeeds with warnings instead of failing - Remaining warnings are harmless JSON lexing issues Build now succeeds with only 14 minor warnings (down from 56 errors).
Simplified documentation based on feedback - removed excessive content and focused only on what client developers need. Changes: - Removed architecture overview (not needed for client devs) - Removed testing guide (not needed for client devs) - Removed full API reference (only documented client-facing APIs) - Removed duplicate existing docs (development.md, pianoteq-api.md, systemd.md) - Consolidated into 4 focused pages: - index.rst - Quick start and overview - guide.rst - Client development guide (686 → 274 lines) - api.rst - Client and ClientApi reference (616 → 319 lines) - example.rst - Minimal working client (483 → 172 lines) - data-models.rst - Instrument/Preset docs (580 → 186 lines) Total documentation: ~1,600 lines (down from ~3,900 lines) Build now succeeds with only 1 warning (down from 14).
tlsim
changed the title
Changes based on feedback: 1. Added back existing documentation as includes - Created docs/source/reference/ directory - Included development.md, pianoteq-api.md, systemd.md - Appears in separate 'Reference' section (no duplication) 2. Clarified startup timing language - Changed from 'Pianoteq takes 6-8 seconds to start' - To 'JSON-RPC API initialization' which is more accurate - Added note that timing varies by hardware (faster on non-Pi systems) - Updated in both guide.rst and api.rst The docs now correctly explain that the delay is API initialization and instrument loading, not just Pianoteq startup time.
Added a "Why Use This Instead of Direct JSON-RPC?" section to the documentation landing page explaining the benefits of using the client API, including process management, state synchronization, demo filtering, and a comparison example.
Removed misleading "navigation state" benefit (JSON-RPC already has next/prev with wrapping). Split preset organization into two clearer benefits: - Shortened preset names for small displays - Preset grouping by instrument instead of flat list
Owner
Author
|
Need #50 first |
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.
This commit adds proper documentation generation for the client APIs,
enabling developers to create custom clients for pi-pianoteq.
Documentation Structure:
Key Components:
Documentation Content:
Improved Docstrings:
Build Infrastructure:
Documentation Features:
Integration:
The documentation will be available at:
https://tlsim.github.io/pi-pianoteq/
Addresses #16