fix

app/main.py

@@ -36,12 +36,75 @@ v tele requestu a vrati soubor PDF.
 Pro dokumenty o stovkach az tisicich stranek pouzijte asynchronni endpoint
 POST /jobs. Synchronni POST /convert je urceny pro mensi dokumenty.
 
-Dva render enginy:
+## Render enginy
 
-- weasyprint je vychozi, ma spravne strankovani a nizkou pametovou narocnost,
-  nespousti JavaScript
-- chromium zvladne i dokumenty dokreslovane JavaScriptem, ale nema pouzitelne
-  CSS countery, takze cisla stranek se dopisuji do hotoveho PDF
+- **weasyprint** je vychozi, ma spravne strankovani a nizkou pametovou
+  narocnost, nespousti JavaScript
+- **chromium** zvladne i dokumenty dokreslovane JavaScriptem, ale nema
+  pouzitelne CSS countery, takze cisla stranek se dopisuji do hotoveho PDF
+
+## Strankovani
+
+Nastaveni je rozdelene do ctyr bloku tela requestu.
+
+**page** rozmer a okraje. `format` je nazev formatu (`A4`, `A5`, `A3`,
+`Letter`, `Legal`) nebo explicitni rozmer `210mm 297mm`. `orientation` se
+uplatni jen u nazvu formatu. `margin` jsou ctyri CSS delky. Pokud si zdrojove
+HTML nastavi vlastni `@page`, ma prednost jeho hodnota.
+
+**page_numbers** cislovani stranek, vychozi stav je vypnuto. `format` je
+sablona se zastupnymi symboly `{page}` a `{pages}`, `position` je jeden
+z sesti okrajovych boxu stranky. Rezimy:
+
+- `css` cisla resi CSS countery pri renderu. Nejcistsi vysledek, vyzaduje ale
+  `engine: weasyprint` a `chunking.enabled: false`, protoze v kazde casti se
+  citac stranek restartuje. Jina kombinace vraci 400 `unsupported_combination`.
+- `overlay` cisla se dopisi do hotoveho PDF jako pruhledna vrstva. Funguje
+  vzdy, jedina moznost u clenenych dokumentu a u Chromia. Jen v tomto rezimu
+  se uplatni `start_at`.
+- `auto` zvoli `css` u necleneneho dokumentu renderovaneho WeasyPrintem,
+  jinak `overlay`.
+
+Cisla se kresli do okraje stranky, pri nulovem `margin` se nemaji kam vejit.
+
+**chunking** deleni velkeho dokumentu na casti renderovane samostatne. Drzi
+spotrebu pameti nizko, casti se pak slouci do jednoho souvisleho PDF. Rez
+vznika jen mezi primymi potomky hlavniho kontejneru, tabulka ani odstavec se
+nikdy nerozdeli. Delici body jsou `section`, `article`, `h1`, elementy
+s atributem `data-chunk` a elementy se stylem obsahujicim `page-break-before`
+nebo `break-before`. Dokument bez takovych bodu se vyrenderuje vcelku.
+
+**toc** obsah se skutecnymi cisly stranek. Vyzaduje `engine: weasyprint`.
+Dokument se kvuli nemu renderuje dvakrat, ukazatel postupu proto probehne
+dvakrat. U cleneneho dokumentu nejsou odkazy v obsahu klikatelne, cisla
+stranek jsou spravna a sluzba na to upozorni ve `warnings`.
+
+Rucni zalomeni se resi v samotnem HTML pres CSS `break-before: page`, sluzba
+do neho nezasahuje.
+
+## Uchovavani souboru
+
+Zadny vstup ani vysledek se neuklada trvale. Vsechno zije jen v docasnem
+adresari sluzby a v pameti procesu.
+
+- **POST /convert** vysledek vznikne na disku, odesle se klientovi a hned po
+  odeslani odpovedi se soubor i pracovni adresar smazou. Nic ke stazeni
+  nezustava, opakovane stazeni znamena novou konverzi.
+- **POST /jobs** vysledek zustava na disku, aby sel stahnout pres
+  GET /jobs/{job_id}/result. Meziprodukty se po dokonceni smazou, zustava jen
+  hotove PDF. Doba dostupnosti je `JOB_RESULT_TTL_SECONDS`, vychozi 1 hodina,
+  a odpocitava se od dokonceni jobu. Presny cas je v poli `expires_at`.
+- Po expiraci se soubor smaze i se zaznamem jobu. Dalsi dotaz na job vraci 404
+  `job_not_found`.
+- **DELETE /jobs/{job_id}** zrusi bezici job nebo smaze hotovy vysledek hned,
+  bez cekani na expiraci.
+- Neuspesny job svuj pracovni adresar maze okamzite, na disku po nem nezustane
+  nic.
+- Fronta i evidence jobu jsou v pameti procesu. Restart sluzby znamena ztratu
+  rozpracovanych jobu i hotovych vysledku, ktere jeste nikdo nestahl.
+  Rozpracovane joby se oznaci jako failed s kodem `service_restarted`.
+- Stahovani neni jednorazove. Dokud vysledek nevyprsi, jde ho stahnout
+  opakovane.
 """