tessl/pypi-sphinx-autobuild

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

Overview

Eval results

Files

Command Line Interface

Name: tessl/pypi-sphinx-autobuild
Author: tessl

The sphinx-autobuild command-line interface provides comprehensive options for development server configuration, file watching, build customization, and browser integration. It extends standard Sphinx build arguments with autobuild-specific functionality.

Capabilities

Main Entry Point

The primary entry point that processes command-line arguments and starts the development server.

def main(argv=()):
    """
    Main entry point for sphinx-autobuild command.
    
    Parameters:
    - argv: list[str] | tuple[str, ...], optional - Command line arguments 
      (defaults to sys.argv[1:] if empty)
    
    Raises:
    - SystemExit: On argument parsing errors or Sphinx errors
    - KeyboardInterrupt: Handled gracefully to stop server
    """

Standard Arguments

Accepts all standard Sphinx build arguments plus autobuild-specific options:

# Required arguments (inherited from sphinx-build)
sphinx-autobuild <sourcedir> <outputdir>

# Standard Sphinx options
sphinx-autobuild docs _build/html -b html -E -a -v

Server Configuration

Configure the development server host and port settings.

--port PORT                    # Port to serve documentation (default: 8000, 0 for free port)
--host HOST                    # Hostname to serve on (default: 127.0.0.1)

Usage Examples:

# Use default port 8000
sphinx-autobuild docs _build/html

# Use specific port  
sphinx-autobuild docs _build/html --port 8080

# Find free port automatically
sphinx-autobuild docs _build/html --port 0

# Bind to all interfaces
sphinx-autobuild docs _build/html --host 0.0.0.0

# Custom host and port
sphinx-autobuild docs _build/html --host 192.168.1.100 --port 3000

File Watching Options

Control which files are watched and which are ignored during development.

--ignore PATTERN               # Glob pattern for files to ignore (repeatable)
--re-ignore REGEX              # Regular expression for files to ignore (repeatable) 
--watch DIR                    # Additional directories to watch (repeatable)

Usage Examples:

# Ignore temporary files
sphinx-autobuild docs _build/html --ignore "*.tmp" --ignore "*.swp"

# Ignore with regex patterns
sphinx-autobuild docs _build/html --re-ignore ".*\.backup$" --re-ignore ".*~$"

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

# Combine ignore patterns
sphinx-autobuild docs _build/html --ignore "*.log" --re-ignore "__pycache__"

Build Control Options

Configure the build process and initial behavior.

--no-initial                   # Skip the initial build on startup
--pre-build COMMAND           # Command to run before each build (repeatable)
--post-build COMMAND          # Command to run after each successful build (repeatable)

Usage Examples:

# Skip initial build
sphinx-autobuild docs _build/html --no-initial

# Run pre-build command
sphinx-autobuild docs _build/html --pre-build "echo Starting build"

# Multiple pre/post build commands
sphinx-autobuild docs _build/html \
  --pre-build "python scripts/generate_api.py" \
  --pre-build "echo Pre-processing complete" \
  --post-build "python scripts/validate_links.py" \
  --post-build "echo Build validation complete"

# Complex shell commands (properly quoted)
sphinx-autobuild docs _build/html \
  --pre-build "find . -name '*.py' -exec python -m py_compile {} \;"

Browser Integration

Automatically open browser and control timing.

--open-browser                 # Open browser after building documentation
--delay SECONDS               # Delay before opening browser (default: 5.0)

Usage Examples:

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

# Open browser with custom delay
sphinx-autobuild docs _build/html --open-browser --delay 2.5

# Immediate browser opening
sphinx-autobuild docs _build/html --open-browser --delay 0

Version Information

--version                      # Show sphinx-autobuild version and exit

Complete Example

A comprehensive example showing multiple options:

sphinx-autobuild docs _build/html \
  --port 8080 \
  --host 0.0.0.0 \
  --open-browser \
  --delay 3 \
  --ignore "*.tmp" \
  --ignore "*.log" \
  --re-ignore ".*\.backup$" \
  --watch ../shared \
  --watch ../templates \
  --pre-build "python scripts/update_config.py" \
  --post-build "python scripts/verify_output.py" \
  -b html \
  -E \
  -v

Environment Variables

Debug Output

SPHINX_AUTOBUILD_DEBUG=1      # Enable debug output for file watching

When set to any non-empty value except "0", enables debug output showing file change notifications and ignore filter decisions.

Usage:

SPHINX_AUTOBUILD_DEBUG=1 sphinx-autobuild docs _build/html

Error Handling

The CLI handles various error conditions gracefully:

Argument parsing errors: Shows usage help and exits with error code
Sphinx build failures: Continues serving but displays error message
Pre/post-build command failures: Shows error and continues serving
Port binding failures: Automatically finds alternative port if port 0 specified
Keyboard interrupt: Clean shutdown with farewell message
File permission errors: Graceful error reporting for inaccessible directories