From 2b2057df565f3eca20f863b218b674503c39b9fe Mon Sep 17 00:00:00 2001 From: DemchaAV Date: Mon, 6 Jul 2026 09:45:32 +0100 Subject: [PATCH] docs: add per-module READMEs Each published module (render-pdf / render-docx / render-pptx / templates / testing / the graph-compose wrapper / bundle / fonts / emoji) and the internal build modules (qa / aggregator) gets a README: what the artifact is, when to depend on it versus the alternatives, its key entry points, and links to the root install matrix and the modules migration guide. Coordinates are stated version-free so a module README never drifts from the release version. --- aggregator/README.md | 22 ++++++++++++++++++++++ bundle/README.md | 23 +++++++++++++++++++++++ emoji/README.md | 27 +++++++++++++++++++++++++++ fonts/README.md | 24 ++++++++++++++++++++++++ qa/README.md | 21 +++++++++++++++++++++ render-docx/README.md | 29 +++++++++++++++++++++++++++++ render-pdf/README.md | 37 +++++++++++++++++++++++++++++++++++++ render-pptx/README.md | 24 ++++++++++++++++++++++++ templates/README.md | 34 ++++++++++++++++++++++++++++++++++ testing/README.md | 31 +++++++++++++++++++++++++++++++ wrapper/README.md | 23 +++++++++++++++++++++++ 11 files changed, 295 insertions(+) create mode 100644 aggregator/README.md create mode 100644 bundle/README.md create mode 100644 emoji/README.md create mode 100644 fonts/README.md create mode 100644 qa/README.md create mode 100644 render-docx/README.md create mode 100644 render-pdf/README.md create mode 100644 render-pptx/README.md create mode 100644 templates/README.md create mode 100644 testing/README.md create mode 100644 wrapper/README.md diff --git a/aggregator/README.md b/aggregator/README.md new file mode 100644 index 000000000..3e44ca2b2 --- /dev/null +++ b/aggregator/README.md @@ -0,0 +1,22 @@ +# GraphCompose Build Aggregator + +**Internal reactor module — not published to Maven Central.** Do not depend on it. + +`aggregator/` (artifact `graph-compose-build`) is the non-published reactor parent that builds +the whole project in one pass — the engine and its sibling modules plus the `examples`, +`benchmarks`, and `qa` children. It exists to give a single build entry point and to host the +aggregator-child modules (examples / benchmarks / qa) that inherit their version from it. + +The **published** artifacts (`graph-compose-core`, `graph-compose`, the render backends, +`graph-compose-templates`, `graph-compose-testing`, `graph-compose-bundle`) are standalone +poms — they do **not** use this aggregator as their Maven parent; it only lists them as +`` so a single reactor build compiles everything. + +Build everything: + +```bash +./mvnw -f aggregator/pom.xml clean verify +``` + +Module layout and per-package ownership: [docs/architecture/package-map.md](../docs/architecture/package-map.md). +See [CONTRIBUTING.md](../CONTRIBUTING.md) for the workflow. diff --git a/bundle/README.md b/bundle/README.md new file mode 100644 index 000000000..82b3c1b56 --- /dev/null +++ b/bundle/README.md @@ -0,0 +1,23 @@ +# GraphCompose Bundle + +`io.github.demchaav:graph-compose-bundle` + +The batteries-included aggregate (pom-packaged). One dependency pulls the default PDF stack +(the `graph-compose` wrapper = core + render-pdf), the built-in templates +(`graph-compose-templates`), the bundled Google fonts (`graph-compose-fonts`), and the +colour-emoji set (`graph-compose-emoji`) at compatible versions. + +## When to depend on it + +Depend on it when you want everything wired up in one coordinate — the closest thing to the +pre-split single jar. The office backends (`graph-compose-render-docx` / +`graph-compose-render-pptx`) stay opt-in and are **not** bundled. + +Because it is `pom`-packaged, a dependency on it needs `pom`. + +## Install + +The engine/templates track the GraphCompose train version (lockstep); `graph-compose-fonts` +and `graph-compose-emoji` are pinned to compatible independent versions. Copy-paste snippet +and the full "which artifact?" table: [root README → Installation](../README.md#installation). +Upgrading from 1.x: [modules migration guide](../docs/migration/v2.0.0-modules.md). diff --git a/emoji/README.md b/emoji/README.md new file mode 100644 index 000000000..3a6b50bc8 --- /dev/null +++ b/emoji/README.md @@ -0,0 +1,27 @@ +# GraphCompose Emoji + +`io.github.demchaav:graph-compose-emoji` + +Colour-emoji SVG glyphs (Noto Emoji) plus a GitHub-shortcode index, packaged as an +**independently-versioned** companion artifact (its own `emoji-v*` tag line — it changes only +when the glyph set or shortcode index does, so it does not track the engine version). + +## When to depend on it + +Add it only to render colour emoji. Text without emoji needs nothing, and an unknown shortcode +falls back to its literal text — so a document renders unchanged with or without this artifact. +`graph-compose-bundle` includes it. + +## Usage + +```java +RichText.text("").emoji(":star:", size) // resolves the shortcode to an inline vector glyph +``` + +It is a resource-only jar (glyphs + `emoji-index.properties`); the shortcode resolver in the +engine reads it from the classpath. + +## Install + +Independent version line (`emoji-v*`), pinned to a version compatible with your engine train. +See [root README → Installation](../README.md#installation) for the pinned coordinate. diff --git a/fonts/README.md b/fonts/README.md new file mode 100644 index 000000000..8ac8bc845 --- /dev/null +++ b/fonts/README.md @@ -0,0 +1,24 @@ +# GraphCompose Fonts + +`io.github.demchaav:graph-compose-fonts` + +Bundled Google font binaries for GraphCompose, packaged as an **independently-versioned** +companion artifact (its own `fonts-v*` tag line — it changes rarely, so it does not track the +engine version). Split out of the engine jar in v1.8.0 so an engine upgrade never re-downloads +the curated font set. + +## When to depend on it + +- Pure-text and **standard-14** documents (`FontName.HELVETICA`, `FontName.COURIER`, `TIMES`) + need **nothing extra** — the base-14 are the standard PDF fonts the render backend already + provides. +- Add this artifact only to render in the **bundled Google families**. + +It is a resource-only jar (no public Java API); its families become available to the font +catalog when it is on the classpath. `graph-compose-bundle` includes it. + +## Install + +Independent version line (`fonts-v*`), pinned to a version compatible with your engine train. +See [root README → Installation](../README.md#installation) for the pinned coordinate and the +[v1.8.0 fonts migration note](../docs/migration/v1.8.0-fonts.md). diff --git a/qa/README.md b/qa/README.md new file mode 100644 index 000000000..3bdafbc48 --- /dev/null +++ b/qa/README.md @@ -0,0 +1,21 @@ +# GraphCompose QA + +**Internal module — not published to Maven Central.** Do not depend on it. + +`qa/` (artifact `graph-compose-build`'s `graph-compose-qa` child) holds the **cross-module +test suites and shared fixtures** that cannot live in any single module's own test scope — +tests that need a render backend plus the engine test-jar, or that span core + render-pdf + +templates at once. It is a reactor tail: an aggregator child that depends on the published +modules at test scope, so heavy render/integration tests run here without creating a reactor +cycle back into the lean core. + +Examples of what lives here: template visual-parity and smoke suites, layout-snapshot +extraction tests, the documentation snippet-compile guard, and the dev-tool launcher. + +Run it as part of the reactor: + +```bash +./mvnw -f aggregator/pom.xml test # or: ./mvnw verify -pl :graph-compose-qa -am +``` + +See [CONTRIBUTING.md](../CONTRIBUTING.md) for the build/test workflow. diff --git a/render-docx/README.md b/render-docx/README.md new file mode 100644 index 000000000..375836a67 --- /dev/null +++ b/render-docx/README.md @@ -0,0 +1,29 @@ +# GraphCompose Render — DOCX + +`io.github.demchaav:graph-compose-render-docx` + +The semantic DOCX export backend for GraphCompose, backed by Apache POI. It carries +`DocxSemanticBackend` and brings POI transitively, so a PDF-only consumer never pays for it. + +## When to depend on it + +Add it (at compile scope) only when you export `.docx`. It is **not** included by +`graph-compose`, `graph-compose-core`, or `graph-compose-bundle` — DOCX is opt-in. + +## Usage + +```java +try (var doc = GraphCompose.document().create()) { + doc.pageFlow().addParagraph("Hello, DOCX").build(); + doc.export(new DocxSemanticBackend(), docxFile); +} +``` + +DOCX maps the semantic node graph, not the fixed PDF layout — coverage is narrower than the +PDF backend. + +## Install + +Same version as the rest of the GraphCompose train (lockstep). Copy-paste snippet and the +full "which artifact?" table: [root README → Installation](../README.md#installation). +Upgrading from 1.x: [modules migration guide](../docs/migration/v2.0.0-modules.md). diff --git a/render-pdf/README.md b/render-pdf/README.md new file mode 100644 index 000000000..e0cb5d9a2 --- /dev/null +++ b/render-pdf/README.md @@ -0,0 +1,37 @@ +# GraphCompose Render — PDF + +`io.github.demchaav:graph-compose-render-pdf` + +The PDFBox-backed PDF render backend for GraphCompose. It carries the whole +`com.demcha.compose.document.backend.fixed.pdf` implementation plus the +`engine.render.pdf` render tree, and brings PDFBox and ZXing (barcodes) transitively. + +## When to depend on it + +- You depend on **`graph-compose-core`** directly and want it to render PDF. +- You are **not** already using **`graph-compose`** (the wrapper) or **`graph-compose-bundle`** — + both of those include this backend transitively, so add it only for a lean, explicit setup. + +A bare `graph-compose-core` renders nothing until this artifact is on the classpath; asking +it to build a PDF throws `MissingBackendException`, whose message names this coordinate. + +## Usage + +You don't call the backend directly. It registers a `FixedLayoutBackendProvider` and a +`FontMetricsProvider` via `META-INF/services`, so the core discovers it at runtime and the +normal path just works: + +```java +try (var doc = GraphCompose.document(out).create()) { + doc.pageFlow().addParagraph("Hello, PDF").build(); +} // buildPdf() / toPdfBytes() / toImages() now resolve the PDF backend +``` + +`PdfFixedLayoutBackend` is available if you need the backend explicitly (custom fragment +handlers, options). + +## Install + +Same version as the rest of the GraphCompose train (lockstep). Copy-paste snippet and the +full "which artifact?" table: [root README → Installation](../README.md#installation). +Upgrading from 1.x: [modules migration guide](../docs/migration/v2.0.0-modules.md). diff --git a/render-pptx/README.md b/render-pptx/README.md new file mode 100644 index 000000000..e1f1d8c99 --- /dev/null +++ b/render-pptx/README.md @@ -0,0 +1,24 @@ +# GraphCompose Render — PPTX + +`io.github.demchaav:graph-compose-render-pptx` + +The semantic PPTX export backend for GraphCompose. Split out of the DOCX artifact so a DOCX +consumer never pulls the PPTX code (and vice versa). + +## Status + +`PptxSemanticBackend` is a **slide-safe semantic manifest skeleton** — it validates the node +graph against what a slide surface can represent; full `.pptx` file emission is not built out +yet. Depend on it for the semantic manifest / forward-compatibility, not for production slide +export. Track the [ROADMAP](../ROADMAP.md) for real PPTX output. + +## When to depend on it + +Opt-in, at compile scope, only if you target the PPTX semantic surface. Not included by any +of `graph-compose`, `graph-compose-core`, or `graph-compose-bundle`. + +## Install + +Same version as the rest of the GraphCompose train (lockstep). Copy-paste snippet and the +full "which artifact?" table: [root README → Installation](../README.md#installation). +Upgrading from 1.x: [modules migration guide](../docs/migration/v2.0.0-modules.md). diff --git a/templates/README.md b/templates/README.md new file mode 100644 index 000000000..80ca31202 --- /dev/null +++ b/templates/README.md @@ -0,0 +1,34 @@ +# GraphCompose Templates + +`io.github.demchaav:graph-compose-templates` + +The built-in CV, cover-letter, invoice, and proposal document templates +(`com.demcha.compose.document.templates.**`). Pure authoring code over the canonical DSL — +no engine internals, no PDFBox — so it depends only on `graph-compose-core`. + +## When to depend on it + +Add it when you want the ready-made presets. It is **opt-in**: neither the `graph-compose` +wrapper nor `graph-compose-core` bundles it (`graph-compose-bundle` does). A 1.x caller that +reached a preset through the single jar must add this artifact — the packages are unchanged. + +## Usage + +Each preset is a final class with a `create(BrandTheme)` factory returning a +`DocumentTemplate` you compose into an open session: + +```java +try (var doc = GraphCompose.document(out).create()) { + ModernInvoice.create(theme).compose(doc, invoiceSpec); // needs graph-compose-templates +} +``` + +Families: `cv`, `coverletter`, `invoice`, `proposal` — each a layered stack (data / components +/ widgets / presets) over the shared `core` layer (`BrandTheme`, identity, text, widgets). +See the [layered-template guides](../docs/templates/v2-layered/README.md). + +## Install + +Same version as the rest of the GraphCompose train (lockstep). Copy-paste snippet and the +full "which artifact?" table: [root README → Installation](../README.md#installation). +Upgrading from 1.x: [modules migration guide](../docs/migration/v2.0.0-modules.md). diff --git a/testing/README.md b/testing/README.md new file mode 100644 index 000000000..497021bcd --- /dev/null +++ b/testing/README.md @@ -0,0 +1,31 @@ +# GraphCompose Testing + +`io.github.demchaav:graph-compose-testing` + +Consumer testing support: deterministic **layout-snapshot assertions** and **PDF visual +regression** (pixel-diff of rendered pages). Add it at **test scope** to lock the output of +documents you generate. + +## When to depend on it + +Add it (test scope) when you want to catch layout/visual regressions in your own documents. +Not needed at runtime; not bundled by any published artifact. + +## Usage + +```java +// Layout snapshot — asserts the renderer-neutral layout graph is unchanged. +LayoutSnapshotAssertions.assertMatches(session.layoutSnapshot(), "invoice-basic"); + +// Visual regression — pixel-diffs the rendered pages against a committed baseline. +PdfVisualRegression.standard().assertMatchesBaseline("invoice-basic", pdfBytes); +``` + +Update baselines deliberately with the documented system properties +(`LayoutSnapshotAssertions.UPDATE_PROPERTY` / `PdfVisualRegression.APPROVE_PROPERTY`). + +## Install + +Same version as the rest of the GraphCompose train (lockstep). Copy-paste snippet and the +full "which artifact?" table: [root README → Installation](../README.md#installation). +Upgrading from 1.x: [modules migration guide](../docs/migration/v2.0.0-modules.md). diff --git a/wrapper/README.md b/wrapper/README.md new file mode 100644 index 000000000..424fe0b09 --- /dev/null +++ b/wrapper/README.md @@ -0,0 +1,23 @@ +# GraphCompose (compat wrapper) + +`io.github.demchaav:graph-compose` + +The `graph-compose` coordinate — an **empty jar** that depends on `graph-compose-core` + +`graph-compose-render-pdf`. It exists so the 1.x coordinate keeps meaning "PDF out of the +box": a caller who upgrades to 2.0 with `graph-compose` on their classpath renders PDF with +**no code and no dependency change**. + +## When to depend on it + +This is the **default**. Depend on `graph-compose` for the drop-in PDF experience. Reach past +it only to go leaner (`graph-compose-core`, bring your own backend) or fuller +(`graph-compose-bundle`, batteries included). Templates are opt-in — add `graph-compose-templates` +if you used the built-in presets through the 1.x single jar. + +Packaging stays `jar` (never `pom`) so existing `` declarations need no ``. + +## Install + +Same version as the rest of the GraphCompose train (lockstep). Copy-paste snippet and the +full "which artifact?" table: [root README → Installation](../README.md#installation). +Upgrading from 1.x: [modules migration guide](../docs/migration/v2.0.0-modules.md).