feat: stream MkDocs sites by URL

README.md

@@ -1,6 +1,6 @@
 # Binge Docs 🎧
 
-Listen to official FastAPI and Typer documentation from your terminal.
+Listen to deployed MkDocs documentation from your terminal.
 Binge Docs removes visual content, then streams the useful prose through
 Kokoro.
 
@@ -30,24 +30,26 @@ The first playback downloads about 120 MB of Kokoro model files.
 
 ## 📚 Listen
 
-Browse a built-in source interactively:
+Browse any deployed MkDocs site interactively:
 
 ```bash
-binge-docs fastapi
-binge-docs typer
+binge-docs listen https://fastapi.tiangolo.com/
+binge-docs listen https://doughayden.github.io/agent-foundation/
 ```
 
-Open a page directly with a slug or official URL:
+Open a page directly with a relative path or full URL:
 
 ```bash
-binge-docs fastapi --page tutorial/first-steps
-binge-docs typer --page https://typer.tiangolo.com/tutorial/first-steps/
+binge-docs listen https://sqlmodel.tiangolo.com/ --page tutorial/
+binge-docs listen https://typer.tiangolo.com/ \
+  --page https://typer.tiangolo.com/tutorial/first-steps/
 ```
 
 Use `--voice` and `--speed` to customize playback:
 
 ```bash
-binge-docs fastapi --page tutorial/first-steps --voice bf_emma --speed 1.2
+binge-docs listen https://fastapi.tiangolo.com/ \
+  --page tutorial/first-steps/ --voice bf_emma --speed 1.2
 ```
 
 Speed must be between `0.5` and `2.0`. Defaults are `af_heart` and `1.0`.
@@ -62,8 +64,7 @@ Speed must be between `0.5` and `2.0`. Defaults are `af_heart` and `1.0`.
 ## 🛠️ Commands
 
 ```text
-binge-docs fastapi [--page PAGE] [--voice VOICE] [--speed SPEED]
-binge-docs typer [--page PAGE] [--voice VOICE] [--speed SPEED]
+binge-docs listen MKDOCS_URL [--page PAGE] [--voice VOICE] [--speed SPEED]
 binge-docs voices
 binge-docs setup
 binge-docs --version

binge_docs/cli.py

@@ -27,11 +27,9 @@
 
 from binge_docs import __version__
 from binge_docs.documentation_sources import (
-    FASTAPI_SOURCE,
-    TYPER_SOURCE,
     CatalogResult,
     DocumentationPage,
-    DocumentationSource,
+    MkDocsSource,
 )
 from binge_docs.errors import BingeDocsError
 from binge_docs.model_store import ModelPaths, ModelStore
@@ -47,7 +45,7 @@
 
 app = typer.Typer(
     name="binge-docs",
-    help="Choose official documentation and listen from your terminal.",
+    help="Choose a deployed MkDocs site and listen from your terminal.",
     no_args_is_help=True,
     add_completion=True,
 )
@@ -78,43 +76,18 @@ def main(
     """Stream official documentation as speech."""
 
 
-@app.command("fastapi")
-def fastapi_command(
-    page: Annotated[
-        str | None,
-        typer.Option(
-            "--page",
-            "-p",
-            help="Page slug or full fastapi.tiangolo.com URL.",
-        ),
-    ] = None,
-    voice: Annotated[
+@app.command()
+def listen(
+    mkdocs_url: Annotated[
         str,
-        typer.Option("--voice", "-v", help="Kokoro US or UK English voice."),
-    ] = DEFAULT_VOICE,
-    speed: Annotated[
-        float,
-        typer.Option("--speed", "-s", help="Playback speed from 0.5 to 2.0."),
-    ] = 1.0,
-) -> None:
-    """Choose and stream one page from the official FastAPI documentation."""
-
-    _stream_source_command(
-        FASTAPI_SOURCE,
-        page=page,
-        voice=voice,
-        speed=speed,
-    )
-
-
-@app.command("typer")
-def typer_command(
+        typer.Argument(help="HTTPS root URL of a deployed MkDocs site."),
+    ],
     page: Annotated[
         str | None,
         typer.Option(
             "--page",
             "-p",
-            help="Page slug or full typer.tiangolo.com URL.",
+            help="Page path or full URL within the MkDocs site.",
         ),
     ] = None,
     voice: Annotated[
@@ -126,18 +99,17 @@ def typer_command(
         typer.Option("--speed", "-s", help="Playback speed from 0.5 to 2.0."),
     ] = 1.0,
 ) -> None:
-    """Choose and stream one page from the official Typer documentation."""
+    """Choose and stream one page from a deployed MkDocs site."""
 
-    _stream_source_command(
-        TYPER_SOURCE,
-        page=page,
-        voice=voice,
-        speed=speed,
-    )
+    try:
+        source = MkDocsSource(mkdocs_url)
+    except BingeDocsError as error:
+        _exit_with_error(str(error))
+    _stream_source_command(source, page=page, voice=voice, speed=speed)
 
 
 def _stream_source_command(
-    source: DocumentationSource,
+    source: MkDocsSource,
     *,
     page: str | None,
     voice: str,
@@ -405,5 +377,5 @@ def _handle_playback_key(key: str, playback_controller: PlaybackController) -> N
         console.print("[yellow]Stopping playback...[/yellow]")
 
 
-if __name__ == "__main__":
+if __name__ == "__main__":  # pragma: no cover
     app()