README.md

# PI Weekly Newspaper

[![Application Preview](docs/screenshots/mosaic_small.png)](docs/gallery.html)

Generates weekly ePub "newspapers" from the [Plymouth Independent](https://www.plymouthindependent.org/) RSS feed, optimized for the Xtreink X4 e-reader (800x480 screen).

[📸 View all screenshots](docs/screenshots.md) | [🖼️ View Interactive Gallery](docs/gallery.html)

## Screenshots & Gallery

- **[Interactive HTML Gallery](docs/gallery.html)** - A slide deck view of the app's features.
- **[Markdown Screenshots List](docs/screenshots.md)** - A full page showing all screenshots with descriptions.
- **[Large Mosaic](docs/screenshots/mosaic_large.png)** - A high-resolution 4x2 grid of all screenshots (great for sharing).

## Quick Start

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python run.py
```

Open http://localhost:5000 in your browser.

## Features

- **Periodic RSS fetching** with configurable interval
- **Automatic image processing** — downloads, resizes to e-reader constraints, converts to baseline JPEG
- **ePub generation** with articles as chapters, table of contents, and embedded images
- **AI-generated covers** via Pollinations.ai (free, no API key) with text fallback
- **Web UI** accessible from any device on your network
- **Scheduled or manual publishing**

## Usage

1. Click **Fetch Now** on the dashboard to pull articles
2. Go to **Publish**, select the target week, toggle articles on/off
3. Choose a cover method (AI or Text) and click **Generate Issue**
4. Download the `.epub` from the **Issues** archive

## Configuration

Settings are editable via the web UI at `/settings`, or in `config.py`:

- `FEED_URL` — RSS feed URL
- `FETCH_INTERVAL_HOURS` — how often to check for new articles
- `IMAGE_MAX_LANDSCAPE` / `IMAGE_MAX_PORTRAIT` — image bounding box dimensions

### Integration with Grimmory / Booklore

You can automatically push generated issues to a [Grimmory](https://github.com/grimmory-tools/grimmory) or Booklore instance. Create a `.env` file in the root directory (or set these as system environment variables):

```env
GRIMMORY_URL=http://your-grimmory-instance:6060
GRIMMORY_USERNAME=your_username
GRIMMORY_PASSWORD=your_password
GRIMMORY_LIBRARY_ID=optional_library_id
```

*Note: `BOOKLORE_URL`, `BOOKLORE_USERNAME`, `BOOKLORE_PASSWORD`, and `BOOKLORE_LIBRARY_ID` are also supported as deprecated fallbacks for older Booklore instances.*

## Access from Other Devices

The app binds to `0.0.0.0:5000`, so access it from any device on your network using your Mac's IP address (e.g., `http://192.168.1.x:5000`).
feat: full integration — app.py wiring, scheduler startup, route registration, README - Wire blueprints and scheduler into create_app() - Add start_scheduler param to skip scheduler in tests - Fix Setting.get/set to use modern db.session.get() - Remove unused imports from conftest and models - Add README with quick start and usage guide Made-with: Cursor 2026-04-06 15:22:38 -04:00			`# PI Weekly Newspaper`

docs: add application screenshots and interactive gallery - Captured clean, full-page screenshots of all major application views - Added an interactive HTML slide deck gallery for previewing features - Created a high-resolution mosaic and a smaller preview mosaic - Generated a Python script to automate mosaic creation - Updated README.md with prominent links to the gallery and screenshots - Added accessibility attributes (role="button", tabindex="0") to calendar rows Made-with: Cursor 2026-04-07 15:03:21 -04:00			`[![Application Preview](docs/screenshots/mosaic_small.png)](docs/gallery.html)`

feat: full integration — app.py wiring, scheduler startup, route registration, README - Wire blueprints and scheduler into create_app() - Add start_scheduler param to skip scheduler in tests - Fix Setting.get/set to use modern db.session.get() - Remove unused imports from conftest and models - Add README with quick start and usage guide Made-with: Cursor 2026-04-06 15:22:38 -04:00			`Generates weekly ePub "newspapers" from the [Plymouth Independent](https://www.plymouthindependent.org/) RSS feed, optimized for the Xtreink X4 e-reader (800x480 screen).`

docs: add application screenshots and interactive gallery - Captured clean, full-page screenshots of all major application views - Added an interactive HTML slide deck gallery for previewing features - Created a high-resolution mosaic and a smaller preview mosaic - Generated a Python script to automate mosaic creation - Updated README.md with prominent links to the gallery and screenshots - Added accessibility attributes (role="button", tabindex="0") to calendar rows Made-with: Cursor 2026-04-07 15:03:21 -04:00			`[📸 View all screenshots](docs/screenshots.md) \| [🖼️ View Interactive Gallery](docs/gallery.html)`

			`## Screenshots & Gallery`

			`- [Interactive HTML Gallery](docs/gallery.html) - A slide deck view of the app's features.`
			`- [Markdown Screenshots List](docs/screenshots.md) - A full page showing all screenshots with descriptions.`
			`- [Large Mosaic](docs/screenshots/mosaic_large.png) - A high-resolution 4x2 grid of all screenshots (great for sharing).`

feat: full integration — app.py wiring, scheduler startup, route registration, README - Wire blueprints and scheduler into create_app() - Add start_scheduler param to skip scheduler in tests - Fix Setting.get/set to use modern db.session.get() - Remove unused imports from conftest and models - Add README with quick start and usage guide Made-with: Cursor 2026-04-06 15:22:38 -04:00			`## Quick Start`

			```bash
			`python -m venv .venv`
			`source .venv/bin/activate`
			`pip install -r requirements.txt`
chore: add run.py entrypoint, update .gitignore and README Moved the app entrypoint from app.py __main__ block to a dedicated run.py. Updated .gitignore to exclude editor, superpowers, and OS files. Made-with: Cursor 2026-04-06 18:39:49 -04:00			`python run.py`
feat: full integration — app.py wiring, scheduler startup, route registration, README - Wire blueprints and scheduler into create_app() - Add start_scheduler param to skip scheduler in tests - Fix Setting.get/set to use modern db.session.get() - Remove unused imports from conftest and models - Add README with quick start and usage guide Made-with: Cursor 2026-04-06 15:22:38 -04:00			```

			`Open http://localhost:5000 in your browser.`

			`## Features`

			`- Periodic RSS fetching with configurable interval`
			`- Automatic image processing — downloads, resizes to e-reader constraints, converts to baseline JPEG`
			`- ePub generation with articles as chapters, table of contents, and embedded images`
			`- AI-generated covers via Pollinations.ai (free, no API key) with text fallback`
			`- Web UI accessible from any device on your network`
			`- Scheduled or manual publishing`

			`## Usage`

			`1. Click Fetch Now on the dashboard to pull articles`
			`2. Go to Publish, select the target week, toggle articles on/off`
			`3. Choose a cover method (AI or Text) and click Generate Issue`
			4. Download the `.epub` from the Issues archive

			`## Configuration`

			Settings are editable via the web UI at `/settings`, or in `config.py`:

			- `FEED_URL` — RSS feed URL
			- `FETCH_INTERVAL_HOURS` — how often to check for new articles
			- `IMAGE_MAX_LANDSCAPE` / `IMAGE_MAX_PORTRAIT` — image bounding box dimensions

feat: add Grimmory/Booklore push integration - Added "Push to Library" button to issues archive - Implemented direct API upload to Grimmory/Booklore - Added support for `.env` files via `python-dotenv` - Handled 409 Conflict for duplicate files gracefully - Resolved library name to numeric ID for direct uploads - Fixed SQLAlchemy and ebooklib warnings in tests - Added comprehensive tests for push functionality Made-with: Cursor 2026-04-07 02:22:35 -04:00			`### Integration with Grimmory / Booklore`

			You can automatically push generated issues to a [Grimmory](https://github.com/grimmory-tools/grimmory) or Booklore instance. Create a `.env` file in the root directory (or set these as system environment variables):

			```env
			`GRIMMORY_URL=http://your-grimmory-instance:6060`
			`GRIMMORY_USERNAME=your_username`
			`GRIMMORY_PASSWORD=your_password`
			`GRIMMORY_LIBRARY_ID=optional_library_id`
			```

			Note: `BOOKLORE_URL`, `BOOKLORE_USERNAME`, `BOOKLORE_PASSWORD`, and `BOOKLORE_LIBRARY_ID` are also supported as deprecated fallbacks for older Booklore instances.

feat: full integration — app.py wiring, scheduler startup, route registration, README - Wire blueprints and scheduler into create_app() - Add start_scheduler param to skip scheduler in tests - Fix Setting.get/set to use modern db.session.get() - Remove unused imports from conftest and models - Add README with quick start and usage guide Made-with: Cursor 2026-04-06 15:22:38 -04:00			`## Access from Other Devices`

			The app binds to `0.0.0.0:5000`, so access it from any device on your network using your Mac's IP address (e.g., `http://192.168.1.x:5000`).