diff --git a/docs/cli/commands.md b/docs/cli/commands.md index be021c2..6ad63e7 100644 --- a/docs/cli/commands.md +++ b/docs/cli/commands.md @@ -1,6 +1,6 @@ # CLI Reference -Reference imported from [v2.4.0](https://github.com/fullbleed-engine/fullbleed-official/blob/56850a6536f9369e17b2344cbf62848c1c783e10/docs/cli.md). Check the installed runtime for your exact version. +Reference imported from [v2.5.0](https://github.com/fullbleed-engine/fullbleed-official/blob/v2.5.0/docs/cli.md). Check the installed runtime for your exact version. Executable entrypoint: @@ -96,6 +96,7 @@ High-value options: - input: `--html` / `--html-str`, `--css`, `--css-str` - output: `--out` +- development (2.5.0+): `--watch`, repeatable `--watch-path`, `--watch-interval`, `--watch-debounce`; see [automatic rebuilds](../guides/render-watch.md) - assets: `--asset`, `--asset-kind`, `--asset-name`, `--asset-trusted` - template compose (auto-finalize): `--template-binding`, `--templates`, `--template-dx`, `--template-dy` - page/pdf: `--page-size`, `--page-width`, `--page-height`, `--margin`, `--pdf-version`, `--pdf-profile` diff --git a/docs/guides/render-watch.md b/docs/guides/render-watch.md new file mode 100644 index 0000000..10fe3a8 --- /dev/null +++ b/docs/guides/render-watch.md @@ -0,0 +1,100 @@ +--- +title: Rebuild PDFs automatically while editing HTML and CSS +description: Use Fullbleed render --watch to rebuild a PDF and PNG previews after saving HTML, CSS, or assets. Includes a runnable invoice, JSON results, and recovery behavior. +--- +# Rebuild PDFs as you edit + +Save your HTML or CSS and let Fullbleed rebuild the document. Watch mode writes +an initial PDF, then keeps running and rebuilds after input changes. It uses +Python's standard library and adds no extra runtime package. + +**Requires Fullbleed 2.5.0 or newer.** Check your version with +`python -m fullbleed --version`. + +## Try the invoice example + +Use a Python 3.10–3.14 virtual environment: + +```bash +python -m pip install --upgrade "fullbleed>=2.5.0,<3" +git clone https://github.com/fullbleed-engine/fullbleed-official.git +cd fullbleed-official/examples/render_watch +python -m fullbleed render --html invoice.html --css styles.css --asset "@noto-sans" --out invoice.pdf --emit-image preview --watch +``` + +Open `invoice.pdf` or the PNG in `preview/`. Change the heading color in +`styles.css`, save, and inspect the regenerated file. The font is bundled in +the wheel. Press **Ctrl-C** to stop; omit `--watch` to render once. + +[Get the complete example](https://github.com/fullbleed-engine/fullbleed-official/tree/v2.5.0/examples/render_watch){ .md-button .md-button--primary } + +Fullbleed writes the PDF and preview files. Your viewer handles opening and +refreshing them; use a viewer that reloads changed files if you want a live +view. On Windows, close a PDF viewer that locks the output file, or inspect +the PNG instead. + +The sample uses fictional data and static amounts. Update the total if you +change its line items; rendering does not calculate invoice arithmetic. + +## Choose what to watch + +Explicit HTML, CSS, and `--asset` files are watched automatically. So are local +file-backed page margins, PDF/VT jobs, template bindings and template maps, +output-intent ICC files, watermark images, and reproducibility-check inputs. + +Add any other dependency with `--watch-path`. Repeat it for multiple files or +directories; directories are scanned recursively, including newly created files: + +```bash +python -m fullbleed render --html invoice.html --css styles.css --asset "@noto-sans" --out invoice.pdf --emit-image preview --watch --watch-path assets --watch-path templates +``` + +Paths referenced *inside* HTML, CSS, or a JSON file are not automatically +discovered. For example, add a PDF referenced by a template map as a watch path. +An extra path triggers rendering but does not make its contents an asset or +template input: configure those inputs with the ordinary render options. + +If Python generates your HTML from data, keep that generation step in your +application and let Fullbleed watch the resulting HTML file. Watch mode does +not rerun Python scripts or transform a watched JSON file into HTML. + +## Saving and recovering from errors + +The default polling interval is **0.5 seconds**, with a **0.2-second debounce** +after the last observed change. Set `--watch-interval` and `--watch-debounce` +to adjust them. A burst of saves becomes one rebuild; an edit made during a +render triggers another pass. + +If an editor temporarily removes an input during a save, the error is reported +and the process keeps watching. Restore or fix the file, and the next change +triggers another render. Failed quality gates also leave the watcher running. +A quality-gate failure can already have written a PDF, so use the latest result +to decide whether the output passed. + +When a successful render shrinks the document, old PNG previews from that watch +session are removed only if they are still unmodified. Unrelated or manually +edited files are left alone. + +## Read results from another tool + +```bash +python -m fullbleed --json-only render --html invoice.html --css styles.css --asset "@noto-sans" --out invoice.pdf --watch +``` + +Stdout contains newline-delimited JSON with the existing +`fullbleed.render_result.v1` and `fullbleed.error.v1` schemas. Successful results +include the PDF SHA-256 at `outputs.sha256`. `--emit-manifest manifest.json` +refreshes a manifest on each cycle. JSON-only mode emits no watch status lines. + +## Keep the loop predictable + +- Use local file dependencies and a file for `--out`; HTML/CSS stdin and PDF stdout are unsupported. Inline HTML needs another local input or an explicit watch path. +- CLI output files and the preview directory are excluded from scans. Common cache/build directories are skipped beneath recursive roots, and nested directory symlinks are not followed. +- Put redirected stdout and application logs outside recursive watch paths. Fullbleed cannot identify arbitrary logs as its own outputs. +- Run one watcher per output path. +- Use a one-shot `render` or `verify` command for a delivery or CI gate. A watch process continues after failures and exits when interrupted. + +See the [CLI reference](../cli/commands.md) for render flags and the +[source guide](https://github.com/fullbleed-engine/fullbleed-official/blob/v2.5.0/docs/render-watch.md) +for the full contract. [Report an issue](https://github.com/fullbleed-engine/fullbleed-official/issues) +with the command, installed version, and a small input that reproduces it. diff --git a/docs/index.md b/docs/index.md index 4c0bf02..a5a27ba 100644 --- a/docs/index.md +++ b/docs/index.md @@ -78,10 +78,13 @@ Path("invoice.pdf").write_bytes(pdf) The wheel bundles a Rust rendering engine, a Python API, a CLI, and fonts. It requires no third-party Python runtime packages. You can render, preview, inspect, and verify in the same workflow. +While editing HTML and CSS, [watch mode](guides/render-watch.md) rebuilds your +PDF and PNG previews after saves. It is available in Fullbleed 2.5.0 and newer. + Fullbleed uses static HTML/CSS as its layout language. Read the [CSS coverage](css-coverage.md) for your templates, and the [tool selection guide](guides/comparison.md) when you also need live browser rendering or general PDF editing. ## Open source, with inspectable evidence -Fullbleed is [MIT licensed](https://github.com/fullbleed-engine/fullbleed-official/blob/master/LICENSE). The [2.4.0 release](https://github.com/fullbleed-engine/fullbleed-official/releases/tag/v2.4.0) includes downloadable wheels and retained engineering evidence. The [performance report](guides/performance.md) describes specific measured workloads and their limits. +Fullbleed is [MIT licensed](https://github.com/fullbleed-engine/fullbleed-official/blob/master/LICENSE). The [2.5.0 release](https://github.com/fullbleed-engine/fullbleed-official/releases/tag/v2.5.0) includes downloadable wheels and retained engineering evidence. The [performance report](guides/performance.md) describes specific measured workloads and their limits. [Read the Python API](engine/pdf-engine.md) · [Set up a coding agent](guides/ai-agents.md) · [Report an issue](https://github.com/fullbleed-engine/fullbleed-official/issues) diff --git a/mkdocs.yml b/mkdocs.yml index 3d215c7..e30917c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -73,6 +73,7 @@ nav: - Examples and downloads: examples.md - Build a document: - Invoices from data: guides/invoices.md + - Rebuild as you edit: guides/render-watch.md - FastAPI, Flask, and Django: guides/web-frameworks.md - Variable-data documents: guides/bank-statements.md - Tagged PDF and accessibility: accessibility/overview.md