Add Sphinx docs site with example previews; fix dropped PDF background

README.md

@@ -1,2 +1,132 @@
-# yamlreports
-
+<p align="center">
+  <img src="ymprintlogolarge.png" alt="YMPrint" width="420">
+</p>
+
+<h3 align="center">Desktop publishing with YAML</h3>
+<p align="center"><em>The technology of the year 2000…today!</em></p>
+
+YMPrint is a Python-based PDF authoring application geared towards professionals who need to
+generate lots of PDF documents. You write the content of your report in YAML (as opposed to
+Markdown) and YMPrint renders it to PDF with near-instant speeds. YMPrint lets you use Python
+scripting within your document, create variables, render variable values, and pass live
+Python objects between report **blocks** to create a truly expressive authoring
+system—the likes of which have not been created before.
+
+```yaml
+Site inspection report:
+  - >
+    This is the first paragraph. The `>` character tells YAML you are entering a
+    multi-line string that should be word-wrapped. Leave a blank line to start a
+    new paragraph.
+  - Findings:
+    - Bullets:
+      - The handrail is loose on the north stair.
+      - Two ceiling tiles are water-stained in the lobby.
+    - Items observed:
+      - Item Number: 12.01
+        Description: There is a problem here. This report documents it.
+        Location: Under the stairs
+```
+
+```bash
+ym convert report.yml
+# ✍️ .... 📝 ... PDF created: report.pdf
+```
+
+## Why YMPrint?
+
+- **Readable source.** Your document *is* the outline. YAML nesting is the document
+  hierarchy — no markup soup, no LaTeX, no HTML.
+- **Batteries included.** Bundled fonts, sensible default styles, and a set of blocks for
+  the content markdown can't express.
+- **Dynamic content.** Interpolate variables with Jinja, execute `_py` blocks, load JSON,
+  embed matplotlib figures, and auto-fill PDF form fields.
+- **Custom templates.** Overlay your document onto a designed PDF background and
+  auto-populate its form fields from document variables.
+
+## Installation
+
+Requires **Python 3.14+**.
+
+```bash
+# With uv (recommended) — installs the `ym` command
+uv tool install ymprint
+
+# Or with pip
+pip install ymprint
+```
+
+From source:
+
+```bash
+git clone https://github.com/StructuralPython/yamlreports.git
+cd yamlreports
+uv sync
+uv run ym --help
+```
+
+## Usage
+
+YMPrint installs a single command, `ym`, with two subcommands.
+
+### `ym convert` — render once
+
+```bash
+ym convert report.yml               # writes report.pdf next to the source
+ym convert report.yml out/doc.pdf   # choose an output path
+```
+
+### `ym live` — hot-reload preview
+
+Renders the PDF, opens it in the [Okular](https://okular.kde.org/) viewer, and rebuilds on
+every save. Great for drafting.
+
+```bash
+ym live report.yml
+```
+
+## Core concepts
+
+- **Keys are headings.** A mapping key whose value is content becomes a heading; the value
+  is laid out underneath it. Lists render in order, lists of mappings render as tables.
+- **Configuration** lives in underscore-prefixed front matter — `_doc` (page template),
+  `_style` (text styles), and `_tablestyle` (table styles) — resolved across three
+  inheriting priority levels: internal defaults → project config → document front matter.
+- **Variables** are defined in `_vars`, interpolated into text with Jinja (`{{name}}`), and
+  passed as real Python objects into blocks with the `$name` syntax.
+- **Blocks** are underscore-prefixed keys that expand into custom content:
+
+  | Block | Purpose |
+  | --- | --- |
+  | `_img` | Embed an image with a caption |
+  | `_matplotfig` | Embed a matplotlib figure |
+  | `_info` / `_warning` / `_danger` / `_tip` / `_note` | Admonition callouts |
+  | `_blockquote` | A quotation with attribution |
+  | `_code` | A non-executable, syntax-highlighted code block |
+  | `_py` | Execute Python and optionally show the source |
+  | `_loadjson` | Load variables from a JSON file |
+  | `_pagebreak` | Force a page break |
+  | `_hrule` | A configurable horizontal rule |
+  | `_spacer` | Insert vertical whitespace |
+
+## Examples
+
+The [`Examples/`](Examples) directory contains a runnable report for each major feature —
+a simple document, document configuration, variables, PDF backgrounds, Python execution,
+and the full set of blocks. Render any of them with `ym convert`.
+
+## Documentation
+
+The full documentation site lives in [`docs/`](docs) (Sphinx + the Shibuya theme). Build it
+locally with:
+
+```bash
+uv run --with-requirements docs/requirements.txt \
+    sphinx-build -b html docs docs/_build/html
+```
+
+Then open `docs/_build/html/index.html`. See [`docs/README.md`](docs/README.md) for details.
+
+## License
+
+See [LICENSE](LICENSE).

docs/README.md

@@ -0,0 +1,38 @@
+# YMPrint documentation
+
+This directory contains the [Sphinx](https://www.sphinx-doc.org/) documentation site for
+YMPrint, using the [Shibuya](https://shibuya.lepture.com/) theme (light) by lepture and
+authored in [MyST](https://myst-parser.readthedocs.io/) markdown.
+
+## Build
+
+```bash
+# From the repo root, into an isolated environment:
+uv run --with-requirements docs/requirements.txt \
+    sphinx-build -b html docs docs/_build/html
+
+# Or with a plain virtualenv:
+pip install -r docs/requirements.txt
+sphinx-build -b html docs docs/_build/html
+```
+
+Open `docs/_build/html/index.html` in a browser.
+
+## Live rebuild while writing
+
+```bash
+uv run --with-requirements docs/requirements.txt \
+    --with sphinx-autobuild \
+    sphinx-autobuild docs docs/_build/html
+```
+
+## Layout
+
+| Path | Contents |
+| --- | --- |
+| `conf.py` | Sphinx configuration (Shibuya light theme, MyST). |
+| `index.md` | Landing page. |
+| `installation.md`, `quickstart.md` | Getting started. |
+| `guide/` | Task-oriented guides (structure, configuration, variables, PDF backgrounds). |
+| `reference/` | Reference material (blocks, CLI, fonts). |
+| `_static/custom.css` | Small theme refinements. |

docs/_static/custom.css

@@ -0,0 +1,142 @@
+/* YMPrint documentation — small refinements on top of the Shibuya light theme */
+
+:root {
+  --ym-accent: #7c3aed;
+}
+
+/* Give code blocks a touch more breathing room */
+.highlight pre {
+  line-height: 1.5;
+}
+
+/* Landing hero */
+.ym-hero {
+  padding: 1.5rem 0 0.75rem;
+  text-align: center;
+}
+
+.ym-hero .ym-logo {
+  display: block;
+  margin: 0 auto 1rem;
+  width: 100%;
+  max-width: 420px;
+  height: auto;
+}
+
+.ym-hero p.ym-tagline {
+  font-size: 1.5rem;
+  font-weight: 700;
+  color: var(--sy-c-text, #24292f);
+  margin: 0.25rem 0 0.15rem;
+}
+
+.ym-hero p.ym-subtagline {
+  font-size: 1.05rem;
+  font-style: italic;
+  color: var(--sy-c-text-secondary, #57606a);
+  margin: 0 0 0.5rem;
+}
+
+/* Inline "block code" chips in prose, e.g. _img, _spacer */
+code.literal {
+  white-space: nowrap;
+}
+
+/* Rendered-PDF page previews in the Examples gallery */
+.ym-page-shot img,
+img.ym-page-shot {
+  width: 100%;
+  height: auto;
+  border: 1px solid var(--sy-c-border, #d0d7de);
+  border-radius: 6px;
+  box-shadow: 0 2px 10px rgba(0, 0, 0, 0.12);
+  background: #fff;
+}
+
+.ym-page-caption {
+  margin-top: 0.35rem;
+  font-size: 0.85rem;
+  color: var(--sy-c-text-secondary, #57606a);
+  text-align: center;
+}
+
+/* Clickable previews: show they can be enlarged */
+img.ym-zoomable {
+  cursor: zoom-in;
+  transition: box-shadow 0.15s ease, transform 0.15s ease;
+}
+
+img.ym-zoomable:hover,
+img.ym-zoomable:focus-visible {
+  box-shadow: 0 6px 20px rgba(0, 0, 0, 0.22);
+  transform: translateY(-2px);
+  outline: 2px solid var(--sy-c-brand, #7c3aed);
+  outline-offset: 3px;
+}
+
+/* Lightbox overlay */
+.ym-lightbox {
+  position: fixed;
+  inset: 0;
+  z-index: 1000;
+  display: none;
+  align-items: center;
+  justify-content: center;
+  padding: 2.5rem;
+  background: rgba(0, 0, 0, 0.82);
+  cursor: zoom-out;
+}
+
+.ym-lightbox.is-open {
+  display: flex;
+}
+
+.ym-lightbox__img {
+  max-width: 95vw;
+  max-height: 92vh;
+  width: auto;
+  height: auto;
+  cursor: default;
+  border-radius: 4px;
+  box-shadow: 0 10px 40px rgba(0, 0, 0, 0.55);
+  background: #fff;
+}
+
+.ym-lightbox__close {
+  position: absolute;
+  top: 1rem;
+  right: 1.25rem;
+  width: 2.5rem;
+  height: 2.5rem;
+  padding: 0;
+  font-size: 1.9rem;
+  line-height: 1;
+  color: #fff;
+  background: rgba(255, 255, 255, 0.12);
+  border: none;
+  border-radius: 50%;
+  cursor: pointer;
+}
+
+.ym-lightbox__close:hover,
+.ym-lightbox__close:focus-visible {
+  background: rgba(255, 255, 255, 0.28);
+  outline: none;
+}
+
+/* Prevent background scroll while the lightbox is open */
+body.ym-lightbox-open {
+  overflow: hidden;
+}
+
+/* A single, centered preview (e.g. the one-page PDF backgrounds example) */
+.ym-single-shot {
+  max-width: 70%;
+  margin: 0 auto;
+}
+
+@media (max-width: 600px) {
+  .ym-single-shot {
+    max-width: 100%;
+  }
+}