152 lines
4.7 KiB
Markdown
152 lines
4.7 KiB
Markdown
# PyWebLayout
|
|
|
|
## Project Status
|
|
|
|
|
|
| Badge | Description |
|
|
|-------|-------------|
|
|
|  | **Test Coverage** - Percentage of code covered by unit tests |
|
|
|  | **Documentation Coverage** - Percentage of code with docstrings |
|
|
|  | **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
|