or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

build.mdcli.mdfiltering.mdindex.mdmiddleware.mdserver.mdutils.md
tile.json

tessl/pypi-sphinx-autobuild

Rebuild Sphinx documentation on changes, with hot reloading in the browser.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/sphinx-autobuild@2025.8.x

To install, run

npx @tessl/cli install tessl/pypi-sphinx-autobuild@2025.8.0

index.mddocs/

Sphinx Autobuild

An automated development server for Sphinx documentation that watches for file changes and automatically rebuilds documentation with hot reloading in the browser. It provides comprehensive command-line interface with options for custom ports, host configuration, file watching patterns, pre/post-build commands, and browser automation.

Package Information

  • Package Name: sphinx-autobuild
  • Language: Python
  • Installation: pip install sphinx-autobuild
  • Requires: Python ≥3.11

Core Imports

import sphinx_autobuild

For programmatic use:

from sphinx_autobuild import __version__
from sphinx_autobuild.__main__ import main
from sphinx_autobuild.build import Builder
from sphinx_autobuild.server import RebuildServer
from sphinx_autobuild.filter import IgnoreFilter
from sphinx_autobuild.middleware import JavascriptInjectorMiddleware, web_socket_script
from sphinx_autobuild.utils import find_free_port, open_browser, show_message, show_command

Basic Usage

Command Line Usage

# Basic usage - watch source directory and serve on localhost:8000
sphinx-autobuild docs _build/html

# Custom port and host
sphinx-autobuild docs _build/html --port 8080 --host 0.0.0.0

# Open browser automatically
sphinx-autobuild docs _build/html --open-browser

# Ignore specific files and patterns
sphinx-autobuild docs _build/html --ignore "*.tmp" --re-ignore ".*\.swp$"

# Watch additional directories
sphinx-autobuild docs _build/html --watch ../source --watch ../templates

# Run pre/post build commands
sphinx-autobuild docs _build/html --pre-build "echo Starting" --post-build "echo Done"

Programmatic Usage

from sphinx_autobuild.__main__ import main

# Run with custom arguments
main(['docs', '_build/html', '--port', '8080'])

# Or use sys.argv style
import sys
sys.argv = ['sphinx-autobuild', 'docs', '_build/html', '--open-browser']
main()

Architecture

Sphinx-autobuild uses an event-driven architecture with several key components:

  • Builder: Manages Sphinx build process and pre/post-build commands
  • RebuildServer: Handles file watching via WebSocket connections with browser clients
  • IgnoreFilter: Filters file changes using glob patterns and regular expressions
  • JavascriptInjectorMiddleware: Injects WebSocket client code into served HTML pages
  • Starlette ASGI App: Serves static files and handles WebSocket connections for hot reloading

The system uses uvicorn as the ASGI server and watchfiles for efficient file system monitoring. When changes are detected, it rebuilds documentation and notifies connected browser clients to reload.

Capabilities

Command Line Interface

Primary way to use sphinx-autobuild with comprehensive options for development server configuration, file watching, build customization, and browser integration.

def main(argv=()):
    """Main entry point for sphinx-autobuild command.
    
    Parameters:
    - argv: Command line arguments (optional, defaults to sys.argv[1:])
    """

Command Line Interface

Build Management

Controls the Sphinx documentation build process with support for pre/post-build commands and error handling.

class Builder:
    def __init__(self, sphinx_args, *, url_host, pre_build_commands, post_build_commands):
        """Initialize builder with Sphinx arguments and command hooks."""
    
    def __call__(self, *, changed_paths):
        """Execute build process when files change."""

Build Management

File Watching & Server

Watches file system for changes and serves documentation with hot reloading via WebSocket connections.

class RebuildServer:
    def __init__(self, paths, ignore_filter, change_callback):
        """Initialize file watching server."""
    
    async def __call__(self, scope, receive, send):
        """ASGI application for WebSocket connections."""

File Watching & Server

File Filtering

Provides flexible file filtering using glob patterns and regular expressions to ignore specific files and directories during watching.

class IgnoreFilter:
    def __init__(self, regular, regex_based):
        """Initialize filter with glob patterns and regex patterns."""
    
    def __call__(self, filename):
        """Check if file should be ignored."""

File Filtering

HTTP Middleware

ASGI middleware for injecting WebSocket client code into HTML responses to enable hot reloading functionality.

class JavascriptInjectorMiddleware:
    def __init__(self, app, ws_url):
        """Initialize middleware with ASGI app and WebSocket URL."""
    
    async def __call__(self, scope, receive, send):
        """ASGI middleware callable for HTTP requests."""

def web_socket_script(ws_url):
    """Generate WebSocket JavaScript code for browser auto-reload."""

HTTP Middleware

Utility Functions

Helper functions for port management, browser automation, and formatted console output.

def find_free_port():
    """Find and return a free port number."""

def open_browser(url_host, delay):
    """Open browser to specified URL after delay."""

def show_message(context):
    """Show message with colored formatting."""

def show_command(command):
    """Show command with colored formatting."""

Utility Functions

Types

# Type aliases used throughout the API
from collections.abc import Callable, Sequence
from pathlib import Path
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    import os
    from starlette.types import ASGIApp, Message, Receive, Scope, Send
    from starlette.websockets import WebSocket
    
# Common type patterns
PathLike = os.PathLike[str]
ChangeCallback = Callable[[Sequence[Path]], None]
CommandList = list[str] | tuple[str, ...]