Add English README and LICENSE

2026-08-20 22:10:44 +02:00
parent d2892003d3
commit 1589762aac
2 changed files with 337 additions and 0 deletions
@@ -0,0 +1,105 @@
+# harbour-calibreweb
+
+**OPDS** client for Sailfish OS: browse and download books from your
+**Calibre Web** instance (or Calibre's Content Server).
+
+Works with any OPDS server, but is designed for Calibre Web:
+navigation feeds, search, covers, downloads with progress.
+
+## Why OPDS instead of the REST API
+
+Recent calibre-web releases (upstream) **no longer ship the REST API**:
+`/api/*` was removed and does not exist in any 0.6.9+ release nor in master.
+The stable, documented interface is **OPDS** (`/opds`, `/opds/new`,
+`/opds/search?query=...`), which uses HTTP Basic Auth and exposes
+per-format download links. OPDS is also supported by Calibre's Content
+Server, so this app covers both backends.
+
+## Features
+
+- Catalog sections (new arrivals, authors, categories, shelves, ...) from the `/opds` index
+- Automatic pagination (`rel="next"` links)
+- Text search (`/opds/search`)
+- Covers with local cache
+- Book detail: author, description, formats with size
+- Download with progress bar to `~/Downloads`
+- HTTP Basic Auth (empty user = anonymous browsing)
+- "Ignore SSL errors" option for self-signed certificates
+
+## Build
+
+You need the [Sailfish SDK](https://sailfishos.org/wiki/Sailfish_SDK)
+(on Linux: `flatpak install flathub org.sailfishos.sdk` or the tarball).
+
+```sh
+git clone <this repo> harbour-calibreweb
+cd harbour-calibreweb
+
+# pick a target, e.g.:
+sfdk target install SailfishOS-4.6.0.11-armv7hl
+sfdk target use SailfishOS-4.6.0.11-armv7hl
+
+sfdk build                 # produces the RPM in RPMS/
+sfdk deploy                # installs on the connected device
+```
+
+Alternatively, install the RPM manually:
+
+```sh
+pkcon install-local harbour-calibreweb-0.1.0-1.armv7hl.rpm
+```
+
+Recommended targets by device: `armv7hl` (Xperia X, Jolla C...),
+`aarch64` (Xperia 10 II/III, Jolla C2), `x86_64` (emulator).
+For the **Jolla Phone 2026** (MediaTek Dimensity, jp2601): `aarch64` with
+Sailfish OS 5.0, e.g. `SailfishOS-5.0.0.62-aarch64` (or the latest 5.0.x
+available in your SDK version).
+
+## Configuration
+
+Open the app → menu → **Settings**:
+
+| Field | Value |
+|---|---|
+| Calibre Web address | e.g. `https://calibre.example.com` (subpath supported) |
+| User | leave empty if anonymous browsing is enabled on calibre-web |
+| Password | your account password (Basic Auth) |
+| Ignore SSL | enable only if the server uses a self-signed certificate |
+
+Then hit **Test connection** and browse.
+
+## Structure
+
+```
+src/                C++: settings (QSettings), apiclient (feeds+covers),
+                    downloader (progress), opdsparser (Atom/OPDS), main
+qml/pages/          MainPage (index), FeedPage (lists+pagination),
+                    BookDetailPage (detail+download), SearchPage, SettingsPage
+qml/cover/          app cover
+icons/              86/108 px icons + generation script
+rpm/                spec and desktop file
+```
+
+## Known limitations
+
+- The password is stored in plain text in the app settings
+  (`/home/nemo/.config/harbour/calibreweb.conf`) — acceptable for personal
+  use. The file is fixed and shared between the launcher (nemo) and SSH
+  debug (defaultuser): the config does not depend on which user launches
+  the app.
+- Search uses the server's engine; results are identical to the web UI.
+- The C++ core (parsing, auth, download) is tested with Qt 5.15 against
+  real OPDS feeds and a Basic Auth mock; the Silica UI requires the SDK
+  for on-device verification.
+
+## Core tests
+
+```sh
+# mock OPDS server + end-to-end test (see local /tmp repo):
+python3 /tmp/mock_opds.py
+# compile and run /tmp/opds_test (Qt 5.15+)
+```
+
+## License
+
+MIT