# 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}%")
```

### EbookReader in Action

Here are animated demonstrations of the EbookReader's key features:

<table>
  <tr>
    <td align="center">
      <b>Page Navigation</b><br>
      <img src="examples/gifs/ereader_page_navigation.gif" width="300" alt="Page Navigation"><br>
      <em>Forward and backward navigation through pages</em>
    </td>
    <td align="center">
      <b>Font Size Adjustment</b><br>
      <img src="examples/gifs/ereader_font_size.gif" width="300" alt="Font Size"><br>
      <em>Dynamic font size scaling with position preservation</em>
    </td>
  </tr>
  <tr>
    <td align="center">
      <b>Chapter Navigation</b><br>
      <img src="examples/gifs/ereader_chapter_navigation.gif" width="300" alt="Chapter Navigation"><br>
      <em>Jump directly to chapters by title or index</em>
    </td>
    <td align="center">
      <b>Bookmarks & Positions</b><br>
      <img src="examples/gifs/ereader_bookmarks.gif" width="300" alt="Bookmarks"><br>
      <em>Save and restore reading positions anywhere in the book</em>
    </td>
  </tr>
</table>

### 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
- **`generate_ereader_gifs.py`** - Generate animated GIF demonstrations
- **`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