caddforge-docs 0.3.0__py3-none-any.whl

caddforge_docs/__init__.py

@@ -0,0 +1 @@
+"""Installed documentation and optional CLI command for CADDForge."""

caddforge_docs/cli.py

@@ -0,0 +1,20 @@
+"""The optional ``caddforge docs`` command."""
+
+from __future__ import annotations
+
+import typer
+
+from .server import serve_documentation, site_directory
+
+
+def docs(
+    host: str = typer.Option("127.0.0.1", "--host", help="Hostname or IP address to bind."),
+    port: int = typer.Option(0, "--port", min=0, max=65535, help="Port; 0 selects a free port."),
+    no_browser: bool = typer.Option(False, "--no-browser", help="Serve without opening a browser."),
+) -> None:
+    """Open the installed documentation and serve it until Ctrl+C."""
+    try:
+        serve_documentation(site_directory(), host=host, port=port, open_browser=not no_browser)
+    except (OSError, RuntimeError, ValueError) as exc:
+        typer.echo(f"Could not open documentation: {exc}", err=True)
+        raise typer.Exit(code=1) from exc

caddforge_docs/server.py

@@ -0,0 +1,124 @@
+"""Serve installed documentation without build tools or a source checkout."""
+
+from __future__ import annotations
+
+from functools import partial
+from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
+from ipaddress import ip_address
+from pathlib import Path
+import socket
+from threading import Thread
+from typing import BinaryIO, Callable
+import webbrowser
+
+
+def site_directory() -> Path:
+    """Locate the site shipped in the installed package."""
+    site = Path(__file__).resolve().parent / "site"
+    if not (site / "index.html").is_file():
+        raise RuntimeError(
+            "The installed documentation site is missing. Reinstall caddforge-docs "
+            "from a built wheel, or rebuild its editable installation."
+        )
+    return site
+
+
+class DocumentationHandler(SimpleHTTPRequestHandler):
+    """Serve site files quietly, without directory listings."""
+
+    def log_message(self, format: str, *args: object) -> None:
+        """Keep normal browser requests out of the command's terminal output."""
+
+    def list_directory(self, path: str) -> BinaryIO | None:
+        """Return a normal missing-page error for directories without an index."""
+        self.send_error(404, "Documentation page not found")
+        return None
+
+
+def create_server(site: Path, host: str, port: int) -> ThreadingHTTPServer:
+    """Bind a site server using IPv4, IPv6, or a resolvable hostname."""
+    if not host.strip():
+        raise ValueError("--host must be a hostname or IP address")
+    addresses = socket.getaddrinfo(host, port, type=socket.SOCK_STREAM, proto=socket.IPPROTO_TCP)
+    last_error: OSError | None = None
+    seen: set[tuple[int, tuple]] = set()
+    for family, _, _, _, address in addresses:
+        if family not in (socket.AF_INET, socket.AF_INET6) or (family, address) in seen:
+            continue
+        seen.add((family, address))
+
+        class DocumentationServer(ThreadingHTTPServer):
+            address_family = family
+
+        try:
+            return DocumentationServer(
+                address, partial(DocumentationHandler, directory=str(site.resolve()))
+            )
+        except OSError as exc:
+            last_error = exc
+    if last_error is not None:
+        raise last_error
+    raise OSError(f"No usable listening address for {host!r}")
+
+
+def browser_url(server: ThreadingHTTPServer) -> str:
+    """Return a connectable URL, using loopback for wildcard bindings."""
+    host, port = server.server_address[:2]
+    address = ip_address(host.split("%", 1)[0])
+    if address.is_unspecified:
+        host = "::1" if address.version == 6 else "127.0.0.1"
+    elif address.version == 6 and "%" not in host and len(server.server_address) > 3:
+        scope = server.server_address[3]
+        if scope:
+            host += f"%{scope}"
+    if address.version == 6:
+        host = "[" + host.replace("%", "%25") + "]"
+    return f"http://{host}:{port}/"
+
+
+def _wait_for_server(thread: Thread) -> None:
+    """Keep the CLI in the foreground while its HTTP worker serves requests."""
+    while thread.is_alive():
+        thread.join(timeout=0.25)
+
+
+def serve_documentation(
+    site: Path,
+    *,
+    host: str,
+    port: int,
+    open_browser: bool = True,
+    emit: Callable[[str], None] = print,
+) -> None:
+    """Open a bound HTTP server and stop it cleanly on Ctrl+C.
+
+    Args:
+        site: Built documentation directory.
+        host: Listening hostname or address.
+        port: Listening port; zero selects an available port.
+        open_browser: Whether to launch the system's default browser.
+        emit: Terminal output callback.
+    """
+    with create_server(site, host, port) as server:
+        url = browser_url(server)
+        thread = Thread(target=server.serve_forever, name="caddforge-docs", daemon=True)
+        thread.start()
+        try:
+            listening_host = server.server_address[0]
+            if server.address_family == socket.AF_INET6:
+                listening_host = f"[{listening_host}]"
+            emit(f"Serving documentation on {listening_host}:{server.server_port}")
+            emit(f"Documentation: {url}")
+            emit("Press Ctrl+C to stop the documentation server.")
+            if open_browser:
+                try:
+                    if not webbrowser.open(url, new=2):
+                        emit(f"Could not open a browser automatically. Open {url} manually.")
+                except Exception as exc:
+                    emit(f"Could not open a browser automatically ({exc}). Open {url} manually.")
+            _wait_for_server(thread)
+        except KeyboardInterrupt:
+            emit("Documentation server stopped.")
+        finally:
+            server.shutdown()
+            thread.join()