# PyWebLayout

## Project Status


| Badge | Description |
|-------|-------------|
| ![Test Coverage](https://gitea.tourolle.paris/dtourolle/pyWebLayout/raw/branch/badges/cov_info/coverage.svg) | **Test Coverage** - Percentage of code covered by unit tests |
| ![Documentation Coverage](https://gitea.tourolle.paris/dtourolle/pyWebLayout/raw/branch/badges/cov_info/coverage-docs.svg) | **Documentation Coverage** - Percentage of code with docstrings |
| ![License](https://img.shields.io/badge/license-MIT-blue.svg) | **License** - Project licensing information |
A Python library for HTML-like layout and rendering.
> 📋 **Note**: Badges show results from the commit referenced in the URLs. Red "error" badges indicate build failures for that specific step.
## Description

PyWebLayout is a Python library for rendering HTML and EPUB content to paginated images. The library provides a high-level **EbookReader** API for building interactive ebook reader applications, along with powerful HTML-to-page rendering capabilities.

## Key Features

### EbookReader - High-Level API
- 📖 **EPUB Support** - Load and render EPUB files
- 📄 **Page Rendering** - Render pages as PIL Images
- ⬅️➡️ **Navigation** - Forward and backward page navigation
- 🔖 **Bookmarks** - Save and load reading positions
- 📑 **Chapter Navigation** - Jump to chapters by title or index
- 🔤 **Font Control** - Adjust font size dynamically
- 📏 **Spacing Control** - Customize line and paragraph spacing
- 📊 **Progress Tracking** - Monitor reading progress

### Core Capabilities
- HTML-to-page layout system
- Multi-page document rendering
- Advanced text rendering with font support
- Position tracking across layout changes
- Intelligent line breaking and pagination

## Installation

```bash
pip install pyWebLayout
```

## Quick Start

### EbookReader - Recommended API

```python
from pyWebLayout.layout.ereader_application import EbookReader

# Create an ebook reader
with EbookReader(page_size=(800, 1000)) as reader:
    # Load an EPUB file
    reader.load_epub("mybook.epub")
    
    # Get current page as PIL Image
    page = reader.get_current_page()
    page.save("page_001.png")
    
    # Navigate through pages
    reader.next_page()
    reader.previous_page()
    
    # Save reading position
    reader.save_position("chapter_3")
    
    # Jump to a chapter
    reader.jump_to_chapter("Chapter 5")
    
    # Adjust font size
    reader.increase_font_size()
    
    # Get progress
    progress = reader.get_reading_progress()
    print(f"Progress: {progress*100:.1f}%")
```

### HTML Multi-Page Rendering

```python
from pyWebLayout.io.readers.html_extraction import html_to_blocks
from pyWebLayout.layout.document_layouter import paragraph_layouter
from pyWebLayout.concrete.page import Page

# Parse HTML to blocks
html = """
<h1>Document Title</h1>
<p>First paragraph with <b>bold</b> text.</p>
<p>Second paragraph with more content.</p>
"""
blocks = html_to_blocks(html)

# Render to pages
page = Page(size=(600, 800))
# Layout blocks onto pages using document_layouter
# See examples/ directory for complete multi-page examples
```

## Examples

Check out the `examples/` directory for complete working examples:

- **`simple_ereader_example.py`** - Quick start with EbookReader
- **`ereader_demo.py`** - Comprehensive EbookReader feature demo
- **`html_multipage_demo.py`** - HTML to multi-page rendering
- See `examples/README.md` for full list

## Documentation

- **EbookReader API**: `examples/README_EREADER.md`
- **HTML Rendering**: `examples/README_HTML_MULTIPAGE.md`
- **Architecture**: `ARCHITECTURE.md`
- **Examples**: `examples/README.md`

## License

MIT License

## Author

Duncan Tourolle - duncan@tourolle.paris