Commit 4545b540 authored by Kourser's avatar Kourser
Browse files

docs: publish Podbook documentation in 24 languages on GitLab Pages

parent f5c6c568
Loading
Loading
Loading
Loading
+7 −0
Changes for .gitignore: 7 added lines, 0 removed lines.
Original line number Diff line number Diff line
@@ -17,5 +17,12 @@ Packages/*/.build/
# Local xcodebuild SPM clone cache
.build-spm/

# GitLab Pages output and website package cache
/public/
/website/.npm/

# Release secrets (Apple ID, app-specific password, GitLab token) — never commit
scripts/release.env

# Python localization tooling
__pycache__/

.gitlab-ci.yml

0 → 100644
+60 −0
Changes for .gitlab-ci.yml: 60 added lines, 0 removed lines.
Original line number Diff line number Diff line
# Same shell-runner layout as Envorenn: image: would be ignored by this executor.
stages:
  - test
  - deploy

variables:
  PAGES_URL: "http://kourser.pages.git.cythin.eu/podbook/"
  NPM_CONFIG_CACHE: "$CI_PROJECT_DIR/website/.npm"
  NPM_CONFIG_AUDIT: "false"
  NPM_CONFIG_FUND: "false"

workflow:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS'
      when: never
    - if: '$CI_COMMIT_BRANCH'

.website:
  cache:
    key:
      files:
        - website/package-lock.json
    paths:
      - website/.npm/
  before_script:
    - python3 website/scripts/bootstrap-node.py
    - export PATH="$CI_PROJECT_DIR/website/.node-runtime/bin:$PATH"
    - node --version
    - npm --version
  script:
    - cd website
    - npm ci --no-audit --no-fund
    - npm run check

docs:build:
  extends: .website
  stage: test
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH'

pages:
  extends: .website
  stage: deploy
  pages: true
  script:
    - cd website
    - npm ci --no-audit --no-fund
    - npm run check
    - test -s build/index.html
    - mv build ../public
  artifacts:
    paths:
      - public
  environment:
    name: documentation
    url: $PAGES_URL
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
+9 −0
Changes for README.md: 9 added lines, 0 removed lines.
Original line number Diff line number Diff line
@@ -57,6 +57,11 @@ Le même relevé a montré que le serveur tient déjà les **positions de lectur

## Documents

Le site Docusaurus se trouve dans [`website/`](website/README.md), avec le guide
utilisateur et les études ci-dessous dans une rubrique de conception
distincte. `.gitlab-ci.yml` prépare sa publication sur GitLab Pages depuis la
branche par défaut.

| Document | Contenu |
|---|---|
| [docs/API-CALIBRE.md](docs/API-CALIBRE.md) | Relevé de l'API de `calibre-server`, fait depuis son code source : catalogue, conversion, positions, recherche, écriture. Les pièges de protocole. |
@@ -206,3 +211,7 @@ Trois mesures à faire, une à deux journées, qui déterminent les choix de tou
1. **Le plafond mémoire réel** d'une app sur l'iPad Pro M4, avec et sans l'autorisation. Décide de la taille maximale des modèles embarqués.
2. **Un test de traduction à l'aveugle** sur deux pages d'un de tes livres : Apple, OPUS-MT, un modèle local 8B, un modèle local 30B sur le Mac, et Claude. C'est le seul moyen de savoir si le local suffit, ou si une clé d'API vaut son euro par livre.
3. **Une écoute de Kokoro en français**, comparé à la voix Premium d'Apple. Si la voix système suffit, tout le poste audio tombe à zéro, sur les trois appareils.

L’app et la documentation couvrent les 24 langues d’Envorenn. Voir la
[procédure de localisation](localization/README.md) pour les catalogues,
les pluriels et les contrôles de traduction.
+12 −10
Changes for docs/API-CALIBRE.md: 12 added lines, 10 removed lines.
Original line number Diff line number Diff line
# L'API du serveur Calibre — relevé

Relevé fait le 30 octobre 2026 à partir du code source de Calibre (`src/calibre/srv/`), pas de documentation : il n'en existe pas. Implémenté et couvert par des tests dans [`Sources/CalibreKit`](../Sources/CalibreKit).
> **Dossier technique et conception.** Ce document conserve les études et l’architecture envisagée. Toutes les fonctions décrites ne sont pas nécessairement disponibles ; le [guide utilisateur](/guides/demarrer/) et le code précisent le fonctionnement actuel.

Relevé fait le 30 octobre 2026 à partir du code source de Calibre (`src/calibre/srv/`), pas de documentation : il n'en existe pas. Implémenté et couvert par des tests dans [`Packages/Core/Sources/CalibreKit`](https://git.cythin.eu/Kourser/podbook/-/tree/main/Packages/Core/Sources/CalibreKit).

---

## 1. Avertissement, qui vient du mainteneur lui-même
## 1. Avertissement, qui vient du mainteneur lui-même {/* #1-avertissement-qui-vient-du-mainteneur-lui-même */}

Interrogé sur la documentation de l'API `/ajax`, Kovid Goyal répond qu'elle n'existe pas, que cette surface n'est **ni publique ni stable**, et qu'il faut lire le source. Conséquences retenues dans `CalibreKit` :

@@ -15,7 +17,7 @@ Interrogé sur la documentation de l'API `/ajax`, Kovid Goyal répond qu'elle n'

---

## 2. Trois conventions pour nommer la bibliothèque
## 2. Trois conventions pour nommer la bibliothèque {/* #2-trois-conventions-pour-nommer-la-bibliothèque */}

C'est le piège principal de cette API. Il est encodé une fois dans `CalibreClient.url(path:query:libraryInQuery:)` et vérifié par quatre tests.

@@ -29,7 +31,7 @@ Vérifié dans `srv/utils.py` : `get_library_data()` lit `rd.query.get('library_

---

## 3. Catalogue — `srv/ajax.py`
## 3. Catalogue — `srv/ajax.py` {/* #3-catalogue--srvajaxpy */}

| Route | Rend |
|---|---|
@@ -49,7 +51,7 @@ Deux pièges de décodage, tous deux couverts par des tests :

---

## 4. Conversion — `srv/convert.py`
## 4. Conversion — `srv/convert.py` {/* #4-conversion--srvconvertpy */}

**C'est la découverte qui change l'architecture : le serveur Calibre convertit, par HTTP.**

@@ -80,7 +82,7 @@ GET /get/EPUB/42/L → le fichier, désormais dans l

---

## 5. Position de lecture et annotations — `srv/books.py`
## 5. Position de lecture et annotations — `srv/books.py` {/* #5-position-de-lecture-et-annotations--srvbookspy */}

**Calibre synchronise déjà les positions de lecture, côté serveur.**

@@ -103,7 +105,7 @@ Deux conséquences pour Podbook :

---

## 6. Recherche plein texte — `srv/fts.py`
## 6. Recherche plein texte — `srv/fts.py` {/* #6-recherche-plein-texte--srvftspy */}

| Route | Méthode | Rôle |
|---|---|---|
@@ -115,7 +117,7 @@ L'index doit être activé côté serveur. Podbook n'a donc pas à indexer la bi

---

## 7. Écriture dans la bibliothèque — `srv/cdb.py`
## 7. Écriture dans la bibliothèque — `srv/cdb.py` {/* #7-écriture-dans-la-bibliothèque--srvcdbpy */}

`POST /cdb/cmd/{commande}?library_id=L` exécute une sous-commande `calibredb` sur le serveur. C'est **la** voie supportée pour écrire : `metadata.db` ne tolère pas un second rédacteur.

@@ -125,13 +127,13 @@ Commandes disponibles : `add`, `add_format`, `remove`, `remove_format`, `set_met

---

## 8. OPDS — `srv/opds.py`
## 8. OPDS — `srv/opds.py` {/* #8-opds--srvopdspy */}

`/opds`, `/opds/navcatalog/{which}`, `/opds/category/…`, `/opds/search/{query}`. Standard, stable, annoncé en Bonjour sur le réseau local. C'est le repli quand `/ajax` n'est pas là — notamment face à Calibre-Web.

---

## 9. Ce que cela change pour Podbook
## 9. Ce que cela change pour Podbook {/* #9-ce-que-cela-change-pour-podbook */}

| Hypothèse initiale | Réalité |
|---|---|
+8 −6
Changes for docs/COMPARATIF-BOOKS.md: 8 added lines, 6 removed lines.
Original line number Diff line number Diff line
# Podbook face à Books d'Apple

> **Dossier technique et conception.** Ce document conserve les études et l’architecture envisagée. Toutes les fonctions décrites ne sont pas nécessairement disponibles ; le [guide utilisateur](/guides/demarrer/) et le code précisent le fonctionnement actuel.

Le cahier des charges de ce projet contient une phrase simple : « lire mon ebook
comme sur l'application Books d'Apple ». Ce document regarde ce que cela veut
dire précisément — ce qui est atteint, ce qui ne l'est pas, et ce que Podbook
@@ -7,7 +9,7 @@ fait que Books ne fera jamais.

La colonne Podbook décrit le code tel qu'il est aujourd'hui, pas la feuille de
route. Ce qui n'a pas été vu fonctionner est marqué comme tel ; le détail est
dans la section « Ce qui est vérifié » du [README](../README.md).
dans la section « Ce qui est vérifié » du [README](https://git.cythin.eu/Kourser/podbook/-/blob/main/README.md).

La colonne Books est établie à partir de la fiche App Store et de la
documentation d'Apple. Elle décrit une application qui évolue à chaque version
@@ -15,7 +17,7 @@ d'iOS : à vérifier avant d'en tirer une décision.

---

## 1. Lire un livre — le terrain de Books
## 1. Lire un livre — le terrain de Books {/* #1-lire-un-livre--le-terrain-de-books */}

C'est là que la comparaison compte, parce que c'est l'attente de départ.

@@ -44,7 +46,7 @@ et quatre défauts d'affichage en sont sortis d'un coup.

---

## 2. Les formats
## 2. Les formats {/* #2-les-formats */}

| Format | Books | Podbook |
|---|---|---|
@@ -63,7 +65,7 @@ les appareils.

---

## 3. Ce que Books ne fait pas
## 3. Ce que Books ne fait pas {/* #3-ce-que-books-ne-fait-pas */}

C'est la raison d'être du projet. Les trois besoins de départ sont ici.

@@ -85,7 +87,7 @@ qu'il ne lit pas les ebooks à voix haute. C'est précisément le trajet du mati

---

## 4. Ce que Books fait mieux, et qu'il faut assumer
## 4. Ce que Books fait mieux, et qu'il faut assumer {/* #4-ce-que-books-fait-mieux-et-quil-faut-assumer */}

Un comparatif qui ne dirait que du bien du projet maison ne servirait à rien.

@@ -104,7 +106,7 @@ Un comparatif qui ne dirait que du bien du projet maison ne servirait à rien.

---

## 5. Ce qu'il faut en retenir
## 5. Ce qu'il faut en retenir {/* #5-ce-quil-faut-en-retenir */}

Deux lignes de ce tableau ont bougé depuis : les objectifs de lecture et
l'annotation PDF à l'Apple Pencil existent maintenant dans Podbook. L'objectif
Loading