@@ -12,26 +12,26 @@ 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.
|
||||
PyWebLayout is a Python library for HTML-like layout and rendering to paginated images. It provides a flexible page rendering system with support for borders, padding, text layout, and HTML parsing.
|
||||
|
||||
## 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
|
||||
### Page Rendering System
|
||||
- 📄 **Flexible Page Layouts** - Create pages with customizable sizes, borders, and padding
|
||||
- 🎨 **Styling System** - Control backgrounds, border colors, and spacing
|
||||
- 📐 **Multiple Layouts** - Support for portrait, landscape, and square pages
|
||||
- 🖼️ **Image Output** - Render pages to PIL Images (PNG, JPEG, etc.)
|
||||
|
||||
### 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
|
||||
### Text and HTML Support
|
||||
- 📝 **HTML Parsing** - Parse HTML content into structured document blocks
|
||||
- 🔤 **Font Support** - Multiple font sizes, weights, and styles
|
||||
- ↔️ **Text Alignment** - Left, center, right, and justified text
|
||||
- 📖 **Rich Content** - Headings, paragraphs, bold, italic, and more
|
||||
|
||||
### Architecture
|
||||
- **Abstract/Concrete Separation** - Clean separation between content structure and rendering
|
||||
- **Extensible Design** - Easy to extend with custom renderables
|
||||
- **Type-safe** - Comprehensive type hints throughout the codebase
|
||||
|
||||
## Installation
|
||||
|
||||
@@ -41,106 +41,98 @@ pip install pyWebLayout
|
||||
|
||||
## Quick Start
|
||||
|
||||
### EbookReader - Recommended API
|
||||
### Basic Page Rendering
|
||||
|
||||
```python
|
||||
from pyWebLayout.layout.ereader_application import EbookReader
|
||||
from pyWebLayout.concrete.page import Page
|
||||
from pyWebLayout.style.page_style import PageStyle
|
||||
|
||||
# Create an ebook reader
|
||||
with EbookReader(page_size=(800, 1000)) as reader:
|
||||
# Load an EPUB file
|
||||
reader.load_epub("mybook.epub")
|
||||
# Create a styled page
|
||||
page_style = PageStyle(
|
||||
border_width=2,
|
||||
border_color=(200, 200, 200),
|
||||
padding=(30, 30, 30, 30), # top, right, bottom, left
|
||||
background_color=(255, 255, 255)
|
||||
)
|
||||
|
||||
# Get current page as PIL Image
|
||||
page = reader.get_current_page()
|
||||
page.save("page_001.png")
|
||||
page = Page(size=(600, 800), style=page_style)
|
||||
|
||||
# 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}%")
|
||||
# Render to image
|
||||
image = page.render()
|
||||
image.save("my_page.png")
|
||||
```
|
||||
|
||||
### 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="docs/images/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="docs/images/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="docs/images/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="docs/images/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
|
||||
### HTML Content Parsing
|
||||
|
||||
```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
|
||||
from pyWebLayout.io.readers.html_extraction import parse_html_string
|
||||
from pyWebLayout.style import Font
|
||||
|
||||
# Parse HTML to blocks
|
||||
# Parse HTML to structured 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
|
||||
base_font = Font(font_size=14)
|
||||
blocks = parse_html_string(html, base_font=base_font)
|
||||
|
||||
# blocks is a list of structured content (Paragraph, Heading, etc.)
|
||||
```
|
||||
|
||||
## Visual Examples
|
||||
|
||||
The library supports various page layouts and configurations:
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td align="center" width="33%">
|
||||
<b>Page Styles</b><br>
|
||||
<img src="docs/images/example_01_page_rendering.png" width="250" alt="Page Rendering"><br>
|
||||
<em>Different borders, padding, and backgrounds</em>
|
||||
</td>
|
||||
<td align="center" width="33%">
|
||||
<b>HTML Content</b><br>
|
||||
<img src="docs/images/example_02_text_and_layout.png" width="250" alt="Text Layout"><br>
|
||||
<em>Parsed HTML with various text styles</em>
|
||||
</td>
|
||||
<td align="center" width="33%">
|
||||
<b>Page Layouts</b><br>
|
||||
<img src="docs/images/example_03_page_layouts.png" width="250" alt="Page Layouts"><br>
|
||||
<em>Portrait, landscape, and square formats</em>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
## Examples
|
||||
|
||||
Check out the `examples/` directory for complete working examples:
|
||||
The `examples/` directory contains working demonstrations:
|
||||
|
||||
- **`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
|
||||
### Getting Started
|
||||
- **[01_simple_page_rendering.py](examples/01_simple_page_rendering.py)** - Introduction to the Page system
|
||||
- **[02_text_and_layout.py](examples/02_text_and_layout.py)** - HTML parsing and text rendering
|
||||
- **[03_page_layouts.py](examples/03_page_layouts.py)** - Different page configurations
|
||||
|
||||
### Advanced Examples
|
||||
- **[html_multipage_simple.py](examples/html_multipage_simple.py)** - Multi-page HTML rendering
|
||||
- **[html_multipage_demo_final.py](examples/html_multipage_demo_final.py)** - Complete multi-page layout
|
||||
- **[html_line_breaking_demo.py](examples/html_line_breaking_demo.py)** - Line breaking demonstration
|
||||
|
||||
Run any example:
|
||||
```bash
|
||||
cd examples
|
||||
python 01_simple_page_rendering.py
|
||||
```
|
||||
|
||||
See **[examples/README.md](examples/README.md)** for detailed documentation.
|
||||
|
||||
## Documentation
|
||||
|
||||
- **EbookReader API**: `examples/README_EREADER.md`
|
||||
- **HTML Rendering**: `examples/README_HTML_MULTIPAGE.md`
|
||||
- **Architecture**: `ARCHITECTURE.md`
|
||||
- **Examples**: `examples/README.md`
|
||||
- **[ARCHITECTURE.md](ARCHITECTURE.md)** - Detailed explanation of Abstract/Concrete architecture
|
||||
- **[examples/README.md](examples/README.md)** - Complete guide to all examples
|
||||
- **[examples/README_HTML_MULTIPAGE.md](examples/README_HTML_MULTIPAGE.md)** - HTML rendering guide
|
||||
- **API Reference** - See docstrings in source code
|
||||
|
||||
## License
|
||||
|
||||
|
||||
Reference in New Issue
Block a user