Update coverage badges [skip ci]
This commit is contained in:
Gitea Action
@@ -0,0 +1,213 @@
|
||||
# pyWebLayout Visual Documentation
|
||||
|
||||
This directory contains visual documentation for pyWebLayout, including animated GIF demonstrations of the EbookReader functionality and static example outputs showcasing various features.
|
||||
|
||||
## Generated GIFs
|
||||
|
||||
### 1. Page Navigation (`ereader_page_navigation.gif`)
|
||||
Demonstrates forward and backward page navigation through an EPUB book. Shows smooth transitions between pages using `next_page()` and `previous_page()` methods.
|
||||
|
||||
**Features shown:**
|
||||
- Sequential page advancement
|
||||
- Page-by-page content rendering
|
||||
- Natural reading flow
|
||||
|
||||
### 2. Font Size Adjustment (`ereader_font_size.gif`)
|
||||
Shows dynamic font size scaling from 0.8x to 1.4x and back. The reader maintains the current reading position even as the layout changes with different font sizes.
|
||||
|
||||
**Features shown:**
|
||||
- `increase_font_size()` / `decrease_font_size()`
|
||||
- `set_font_size(scale)` with specific values
|
||||
- Position preservation across layout changes
|
||||
- Text reflow with different sizes
|
||||
|
||||
### 3. Chapter Navigation (`ereader_chapter_navigation.gif`)
|
||||
Demonstrates jumping between chapters in a book. Each chapter's first page is displayed, showing the ability to navigate non-linearly through the content.
|
||||
|
||||
**Features shown:**
|
||||
- `jump_to_chapter(index)` for index-based navigation
|
||||
- `jump_to_chapter(title)` for title-based navigation
|
||||
- `get_chapters()` to list available chapters
|
||||
- Quick access to any part of the book
|
||||
|
||||
### 4. Bookmarks & Positions (`ereader_bookmarks.gif`)
|
||||
Illustrates the bookmark system: navigating to a position, saving it, navigating away, and then returning to the saved position.
|
||||
|
||||
**Features shown:**
|
||||
- `save_position(name)` to bookmark current location
|
||||
- `load_position(name)` to return to saved bookmark
|
||||
- Position stability across navigation
|
||||
- Multiple bookmark support
|
||||
|
||||
## Generating Your Own GIFs
|
||||
|
||||
To generate these animations with your own EPUB file:
|
||||
|
||||
```bash
|
||||
cd examples
|
||||
python generate_ereader_gifs.py path/to/your/book.epub ../docs/images/
|
||||
```
|
||||
|
||||
This will create all four GIF animations in the specified output directory.
|
||||
|
||||
### Script Options
|
||||
|
||||
```python
|
||||
python generate_ereader_gifs.py <epub_path> [output_dir]
|
||||
```
|
||||
|
||||
- `epub_path`: Path to your EPUB file (required)
|
||||
- `output_dir`: Directory to save GIFs (default: current directory)
|
||||
|
||||
### Customization
|
||||
|
||||
You can modify `generate_ereader_gifs.py` to adjust:
|
||||
- Frame duration (`duration` parameter in `create_gif()`)
|
||||
- Page dimensions (change `page_size` in `EbookReader`)
|
||||
- Number of frames for each animation
|
||||
- Font scale ranges
|
||||
- Animation sequences
|
||||
|
||||
## Technical Details
|
||||
|
||||
- **Format**: Animated GIF
|
||||
- **Page Size**: 600x800 pixels
|
||||
- **Frame Rate**: Variable (500-1000ms per frame)
|
||||
- **Loop**: Infinite
|
||||
- **Book Used**: Alice's Adventures in Wonderland (test.epub)
|
||||
|
||||
## File Sizes
|
||||
|
||||
| GIF | Size | Frames | Duration per Frame |
|
||||
|-----|------|--------|-------------------|
|
||||
| `ereader_page_navigation.gif` | ~500 KB | 10 | 600ms |
|
||||
| `ereader_font_size.gif` | ~680 KB | 13 | 500ms |
|
||||
| `ereader_chapter_navigation.gif` | ~290 KB | 11 | 1000ms |
|
||||
| `ereader_bookmarks.gif` | ~500 KB | 17 | 600ms |
|
||||
|
||||
---
|
||||
|
||||
## Example Outputs
|
||||
|
||||
Static PNG images generated by the example scripts, demonstrating various pyWebLayout features.
|
||||
|
||||
### Example 01: Simple Page Rendering
|
||||
**File:** `example_01_page_rendering.png`
|
||||
**Source:** [examples/01_simple_page_rendering.py](../../examples/01_simple_page_rendering.py)
|
||||
**Demonstrates:** Page styles, borders, padding, background colors
|
||||
|
||||
### Example 06: Functional Elements
|
||||
**File:** `example_06_functional_elements.png`
|
||||
**Source:** [examples/06_functional_elements_demo.py](../../examples/06_functional_elements_demo.py)
|
||||
**Demonstrates:** Buttons, form fields, interactive elements
|
||||
|
||||
### Example 08: Pagination (NEW)
|
||||
**Files:**
|
||||
- `example_08_pagination_explicit.png` (109 KB) - 5 pages with explicit PageBreaks
|
||||
- `example_08_pagination_auto.png` (87 KB) - 2 pages with automatic pagination
|
||||
|
||||
**Source:** [examples/08_pagination_demo.py](../../examples/08_pagination_demo.py)
|
||||
**Test:** [tests/examples/test_08_pagination_demo.py](../../tests/examples/test_08_pagination_demo.py)
|
||||
|
||||
**Demonstrates:**
|
||||
- Using `PageBreak` to force content onto new pages
|
||||
- Multi-page document layout with explicit breaks
|
||||
- Automatic pagination when content overflows
|
||||
- Page numbering functionality
|
||||
- Document flow control
|
||||
|
||||
**Coverage:** ✅ Fills critical gap - PageBreak had NO examples before this
|
||||
|
||||
### Example 09: Link Navigation (NEW)
|
||||
**File:** `example_09_link_navigation.png` (60 KB)
|
||||
**Source:** [examples/09_link_navigation_demo.py](../../examples/09_link_navigation_demo.py)
|
||||
**Test:** [tests/examples/test_09_link_navigation_demo.py](../../tests/examples/test_09_link_navigation_demo.py)
|
||||
|
||||
**Demonstrates:**
|
||||
- **Internal links** - Document navigation (`#section1`, `#section2`)
|
||||
- **External links** - Web URLs (`https://example.com`)
|
||||
- **API links** - API endpoints (`/api/settings`, `/api/save`)
|
||||
- **Function links** - Direct function calls (`calculate()`, `process()`)
|
||||
- Link styling (underlined, color-coded by type)
|
||||
- Link callbacks and interactivity
|
||||
|
||||
**Coverage:** ✅ Comprehensive - All 4 LinkType variations demonstrated
|
||||
|
||||
### Example 10: Comprehensive Forms (NEW)
|
||||
**File:** `example_10_forms.png` (31 KB)
|
||||
**Source:** [examples/10_forms_demo.py](../../examples/10_forms_demo.py)
|
||||
**Test:** [tests/examples/test_10_forms_demo.py](../../tests/examples/test_10_forms_demo.py)
|
||||
|
||||
**Demonstrates all 14 FormFieldType variations:**
|
||||
|
||||
**Text-Based Fields:**
|
||||
- `TEXT` - Standard text input
|
||||
- `EMAIL` - Email validation field
|
||||
- `PASSWORD` - Password masking
|
||||
- `URL` - URL validation
|
||||
- `TEXTAREA` - Multi-line text
|
||||
|
||||
**Number/Date/Time Fields:**
|
||||
- `NUMBER` - Numeric input
|
||||
- `DATE` - Date picker
|
||||
- `TIME` - Time selector
|
||||
- `RANGE` - Slider control
|
||||
- `COLOR` - Color picker
|
||||
|
||||
**Selection Fields:**
|
||||
- `CHECKBOX` - Boolean selection
|
||||
- `RADIO` - Single choice from options
|
||||
- `SELECT` - Dropdown menu
|
||||
- `HIDDEN` - Hidden form data
|
||||
|
||||
**Coverage:** ✅ Complete - All 14 field types across 4 practical examples
|
||||
|
||||
---
|
||||
|
||||
## Generating New Examples
|
||||
|
||||
### Run Individual Examples
|
||||
```bash
|
||||
# Navigate to project root
|
||||
cd /path/to/pyWebLayout
|
||||
|
||||
# Run specific example
|
||||
python examples/08_pagination_demo.py
|
||||
python examples/09_link_navigation_demo.py
|
||||
python examples/10_forms_demo.py
|
||||
```
|
||||
|
||||
### Run All Example Tests
|
||||
```bash
|
||||
# Run all example tests with pytest
|
||||
python -m pytest tests/examples/ -v
|
||||
|
||||
# Run specific test file
|
||||
python -m pytest tests/examples/test_08_pagination_demo.py -v
|
||||
```
|
||||
|
||||
All new examples (08, 09, 10) include:
|
||||
- ✅ Comprehensive documentation
|
||||
- ✅ Full test coverage (30 tests total)
|
||||
- ✅ Visual output verification
|
||||
- ✅ Working code examples
|
||||
|
||||
See the main [README.md](../../README.md) and [examples/README.md](../../examples/README.md) for detailed information.
|
||||
|
||||
---
|
||||
|
||||
## Usage in Documentation
|
||||
|
||||
These visual assets are used throughout the pyWebLayout documentation to showcase capabilities.
|
||||
|
||||
To embed in Markdown:
|
||||
```markdown
|
||||
|
||||
|
||||
```
|
||||
|
||||
To embed in HTML with size control:
|
||||
```html
|
||||
<img src="docs/images/ereader_page_navigation.gif" width="300" alt="Page Navigation">
|
||||
<img src="docs/images/example_08_pagination_explicit.png" width="400" alt="Pagination">
|
||||
```
|
||||
Reference in New Issue
Block a user