Docs PR preview + 7 doc.md files + README fixes#479
Conversation
New workflow:
- docs-preview.yaml: auto-builds docs preview on PR open/update,
deploys to pr-{number}/ subdirectory, posts comment with link,
cleans up on PR close/merge
Documentation coverage:
- 7 missing doc.md files: preprocessing, input_output, plotting,
quality_control, ssl_embeddings, speaker_diarization_evaluation,
text/embeddings_extraction
README fixes:
- Documentation URL: sensein.group → sensein.github.io
- tutorials/README.md: added 3 new tutorials
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Both docs.yaml and docs-preview.yaml referenced --extra articulatory which no longer exists. Use --all-extras instead. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a documentation preview workflow for pull requests, enabling automated building, deployment to GitHub Pages subdirectories, and cleanup upon closure. It also improves documentation coverage by adding doc.md files for several audio and text modules, standardizes the documentation URL in the README, and updates the tutorials list. Review feedback suggests addressing potential permission issues for forks in the GitHub Actions workflow, ensuring pdoc correctly includes the new doc.md files via directives, and updating the GPU requirement status for the transcription tutorial.
| **Job 1: build-and-deploy** (triggers on PR opened/synchronize/reopened) | ||
| 1. Build docs with pdoc (same command as release workflow) | ||
| 2. Deploy to `docs` branch under `pr-{PR_NUMBER}/` subdirectory | ||
| 3. Post/update PR comment with preview URL | ||
|
|
||
| **Job 2: cleanup** (triggers on PR closed) | ||
| 1. Remove `pr-{PR_NUMBER}/` from docs branch | ||
| 2. Update PR comment to note preview was removed |
There was a problem hiding this comment.
The proposed workflow using the pull_request trigger for building, deploying, and cleaning up previews will encounter permission issues for pull requests originating from forks. In such cases, the default GITHUB_TOKEN is read-only, which will prevent the deployment to the docs branch and the posting of PR comments. To support external contributions, you might need to use the pull_request_target trigger or a workflow_run based approach, while being mindful of the security implications of running potentially untrusted code from PRs.
| - [ ] T006 [P] [US2] Create src/senselab/audio/tasks/preprocessing/doc.md — describe resample_audios, downmix_audios_to_mono, normalize, chunk_audios; when to use each | ||
| - [ ] T007 [P] [US2] Create src/senselab/audio/tasks/input_output/doc.md — describe read_audios, save_audios; supported formats and file I/O patterns | ||
| - [ ] T008 [P] [US2] Create src/senselab/audio/tasks/plotting/doc.md — describe plot_waveform, plot_specgram, plot_waveform_and_specgram, plot_aligned_panels, play_audio; include panel types for plot_aligned_panels | ||
| - [ ] T009 [P] [US2] Create src/senselab/audio/tasks/quality_control/doc.md — describe QC framework, metrics, checks, taxonomy; reference issue #472 for roadmap | ||
| - [ ] T010 [P] [US2] Create src/senselab/audio/tasks/ssl_embeddings/doc.md — describe self-supervised learning embedding extraction; models supported | ||
| - [ ] T011 [P] [US2] Create src/senselab/audio/tasks/speaker_diarization_evaluation/doc.md — describe DER and other diarization evaluation metrics | ||
| - [ ] T012 [P] [US2] Create src/senselab/text/tasks/embeddings_extraction/doc.md — describe text embedding extraction; HuggingFace and sentence-transformers backends |
There was a problem hiding this comment.
Standalone doc.md files are not automatically picked up by pdoc unless they are explicitly included in the module docstrings. To ensure this content appears in the generated documentation, you may need to add a directive like """.. include:: ./doc.md""" to the __init__.py of each respective module, or move the content directly into the docstrings.
| | voice_activity_detection | Optional | Yes* | Detect speech segments | | ||
| | voice_cloning | Yes | No | Voice conversion | | ||
| | audio_recording_and_acoustic_analysis | No | No | Recording and acoustic feature analysis | | ||
| | transcription_and_phonemic_analysis | No | No | Transcription and phoneme-level analysis | |
There was a problem hiding this comment.
The GPU column for the transcription_and_phonemic_analysis tutorial is marked as No. Given that transcription is a computationally heavy task that benefits significantly from GPU acceleration, it would be more accurate to mark this as Optional (similar to speaker_diarization or speech_enhancement).
| | transcription_and_phonemic_analysis | No | No | Transcription and phoneme-level analysis | | |
| | transcription_and_phonemic_analysis | Optional | No | Transcription and phoneme-level analysis | |
- docs-preview.yaml: add FFmpeg system install step - video/tasks/input_output.py: guard ffmpeg import with try/except (ffmpeg-python was never in pyproject.toml dependencies) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
|
📖 Docs Preview: https://sensein.github.io/senselab/pr-479/ Updated for commit 613bf98 |
GitHub Pages CNAME is sensein.group (confirmed via gh api pages). Updated: docs-preview.yaml comment URL, README.md badge + link, pyproject.toml Documentation URL. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
|
📖 Docs Preview: https://sensein.group/senselab/pr-479/ Updated for commit d4fdc79 |
- 7 __init__.py files updated with """.. include:: ./doc.md""" so pdoc renders the doc.md content in generated documentation - All docs URLs standardized to sensein.group/senselab (the canonical CNAME confirmed via GitHub Pages API) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
|
📖 Docs Preview: https://sensein.group/senselab/pr-479/ Updated for commit 181d327 |
The preview URL now shows as a "View deployment" button in the PR
checks UI via GitHub deployment environments. Each PR gets its own
environment (docs-preview-pr-{number}) which is cleaned up on close.
Removed PR comment posting — the deployment link in the checks UI
is cleaner and doesn't spam the PR thread.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 participant
Summary
New: PR docs preview workflow
pr-{number}/subdirectory on the docs branchDocumentation coverage
README fixes
Partially addresses #418 (docs part — QC doc.md added, QC tutorial is a separate task).
🤖 Generated with Claude Code
Version
Published prerelease version:
1.3.1-alpha.17Changelog
🐛 Bug Fix
Authors: 1