From 1f8c0651ccc6446ee8288da42d2c8446055f09b6 Mon Sep 17 00:00:00 2001 From: Chirag Patil Date: Sat, 13 Jun 2026 23:13:28 +0530 Subject: [PATCH 1/2] docs: shorten README with emojis - Condense setup and usage guidance - Add emoji headings for faster scanning --- README.md | 163 +++++++++++++----------------------------------------- 1 file changed, 38 insertions(+), 125 deletions(-) diff --git a/README.md b/README.md index 01c9cd4..d5be41d 100644 --- a/README.md +++ b/README.md @@ -1,171 +1,84 @@ -# Binge Docs +# Binge Docs 🎧 -Listen to official documentation directly from your terminal. +Listen to official FastAPI and Typer documentation from your terminal. +Binge Docs removes visual content, then streams the useful prose through +Kokoro. -```bash -binge-docs fastapi -binge-docs typer -``` - -Choose a built-in documentation source, search for a page, and start -listening. Binge Docs downloads the selected official page, removes visual -content such as code blocks and tables, and streams the remaining prose -through Kokoro. - -## Requirements - -- Python 3.10 through 3.13 -- An internet connection for the first catalog, page, and model downloads -- A working audio output device -- PortAudio when required by your operating system +## 🚀 Install -On Debian or Ubuntu, install PortAudio before installing Binge Docs: +Requires Python 3.10–3.13, internet access for initial downloads, and audio +output. ```bash -sudo apt-get install portaudio19-dev +uv tool install . ``` -## Install - -Clone this repository and install it with `uv`: +On Debian or Ubuntu, install PortAudio first: ```bash -uv tool install . +sudo apt-get install portaudio19-dev ``` -For local development: +For development: ```bash uv sync uv run binge-docs --help ``` -The first playback downloads approximately 120 MB of Kokoro model files into -your operating system's user cache. - -## Built-In Sources +The first playback downloads about 120 MB of Kokoro model files. -Binge Docs currently ships with: +## 📚 Listen -- FastAPI via `binge-docs fastapi` -- Typer via `binge-docs typer` - -## Choose A Page - -Start the interactive FastAPI browser: +Browse a built-in source interactively: ```bash binge-docs fastapi -``` - -Or browse Typer: - -```bash binge-docs typer ``` -First choose a section such as Tutorial, Advanced, Deployment, How-To, or -Reference. Typer uses sections such as Features, Learn, Reference, Resources, -About, and Release Notes. Then type in the page picker to filter the available -pages. - -During playback: - -- Press `space` to pause or resume -- Press `+` or `-` to change speed for upcoming audio -- Press `q` to stop cleanly -- Press `Ctrl+C` to force stop - -## Open A Page Directly - -Skip the menus with a page slug: +Open a page directly with a slug or official URL: ```bash binge-docs fastapi --page tutorial/first-steps -binge-docs typer --page tutorial/first-steps +binge-docs typer --page https://typer.tiangolo.com/tutorial/first-steps/ ``` -A full official URL also works: +Use `--voice` and `--speed` to customize playback: ```bash -binge-docs fastapi \ - --page https://fastapi.tiangolo.com/tutorial/first-steps/ - -binge-docs typer \ - --page https://typer.tiangolo.com/tutorial/first-steps/ +binge-docs fastapi --page tutorial/first-steps --voice bf_emma --speed 1.2 ``` -Direct page selection is required when the command is run without an -interactive terminal. +Speed must be between `0.5` and `2.0`. Defaults are `af_heart` and `1.0`. -## Voice And Speed +## ⌨️ Controls -Use a supported US or UK English voice: +- `space`: pause or resume +- `+` / `-`: change speed for upcoming audio +- `q`: stop cleanly +- `Ctrl+C`: force stop -```bash -binge-docs fastapi \ - --page tutorial/first-steps \ - --voice bf_emma \ - --speed 1.2 - -binge-docs typer \ - --page tutorial/first-steps \ - --voice bf_emma \ - --speed 1.2 -``` +## 🛠️ Commands -List all supported voices: - -```bash +```text +binge-docs fastapi [--page PAGE] [--voice VOICE] [--speed SPEED] +binge-docs typer [--page PAGE] [--voice VOICE] [--speed SPEED] binge-docs voices -``` - -Playback speed must be between `0.5` and `2.0`. The default voice is -`af_heart`, and the default speed is `1.0`. - -## Model Setup - -Models download automatically on first playback. To download them in advance -or verify and repair existing files, run: - -```bash binge-docs setup +binge-docs --version ``` -Downloads are pinned and verified with SHA-256 checksums before use. - -## Offline Behavior +`binge-docs setup` downloads or repairs checksum-verified model files. -Each built-in source keeps its own catalog and page cache for 24 hours. After -that, Binge Docs tries to refresh the cached content. If the refresh fails, it -uses the stale copy and displays an offline warning. +## 💾 Offline Use -A page that has never been opened cannot be played offline. +Catalogs and pages are cached for 24 hours. If a refresh fails, Binge Docs +uses stale cached content with a warning. Pages that have never been opened +cannot be played offline. -## What Gets Read +## 🔎 What Gets Read -Binge Docs reads: - -- Headings -- Paragraphs -- Lists and blockquotes -- Notes, tips, and warnings -- Link labels and inline code - -It skips: - -- Navigation and page metadata -- Code blocks and terminal output -- Tables and images -- Duplicate tab variants -- Scripts and visual controls - -## Commands - -```text -binge-docs fastapi [--page PAGE] [--voice VOICE] [--speed SPEED] -binge-docs typer [--page PAGE] [--voice VOICE] [--speed SPEED] -binge-docs voices -binge-docs setup -binge-docs --version -``` +Binge Docs reads headings, prose, lists, notes, link labels, and inline code. +It skips navigation, code blocks, terminal output, tables, images, scripts, +and other visual controls. From a6304f782e07c79dd48998612e18947e5ba00823 Mon Sep 17 00:00:00 2001 From: Chirag Patil Date: Sat, 13 Jun 2026 23:16:43 +0530 Subject: [PATCH 2/2] fix: authenticate OpenCode reviews - Use the GitHub Actions token for review comments - Grant issue and pull request write permissions --- .github/workflows/opencode.yml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.github/workflows/opencode.yml b/.github/workflows/opencode.yml index b99f300..5cee80c 100644 --- a/.github/workflows/opencode.yml +++ b/.github/workflows/opencode.yml @@ -33,6 +33,8 @@ jobs: permissions: contents: read id-token: write + issues: write + pull-requests: write steps: - name: Checkout repository uses: actions/checkout@v6 @@ -44,6 +46,7 @@ jobs: uses: anomalyco/opencode/github@latest env: DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }} + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} with: model: deepseek/deepseek-v4-pro - # github_token: xxxx + use_github_token: true