Updates to docs content and tone

Author: connorferster

docs/conf.py

@@ -50,7 +50,7 @@
 html_theme_options = {
     "color_mode": "light",
     "accent_color": "violet",
-    "github_url": "https://github.com/StructuralPython/yamlreports",
+    "github_url": "https://github.com/StructuralPython/ymprint",
     "nav_links": [
         {"title": "Quickstart", "url": "quickstart"},
         {"title": "Blocks", "url": "reference/blocks"},
@@ -61,7 +61,7 @@
 html_context = {
     "source_type": "github",
     "source_user": "StructuralPython",
-    "source_repo": "yamlreports",
+    "source_repo": "ymprint",
 }
 
 pygments_style = "friendly"

docs/installation.md

@@ -2,6 +2,12 @@
 
 YMPrint requires **Python 3.14 or newer**.
 
+## With pip
+
+```bash
+pip install ymprint
+``` 
+
 ## With `uv` (recommended)
 
 [`uv`](https://docs.astral.sh/uv/) is the fastest way to install and run YMPrint as a tool:
@@ -43,16 +49,17 @@ Installing YMPrint pulls in everything needed to render PDFs:
 
 | Dependency | Role |
 | --- | --- |
-| `reportlab` | The PDF layout engine that typesets your story. |
-| `pymupdf` / `pypdf` | Read PDF backgrounds, fill form fields, overlay content. |
+| `reportlab` | The PDF layout engine that typesets your document. |
+| `pymupdf` | Read PDF backgrounds, fill form fields, overlay content. |
 | `jinja2` | Interpolate `_vars` into your content. |
+| `wenmode` | Parses inline markdown (the latest library from lepture!) |
 | `pydantic` | Validate the document, style, and table configuration. |
 | `pygments` | Syntax highlighting for `_code` and `_py` blocks. |
 | `ruamel-yaml` | Parse your report YAML. |
 | `typer` | The `ym` command-line interface. |
 
 A set of fonts is bundled with YMPrint, so documents render consistently on any machine
-without installing system fonts. See the [Fonts reference](reference/fonts.md).
+without needing to rely on system fonts (which may or may not load easily into ReportLab). See the [Fonts reference](reference/fonts.md).
 
 :::{tip}
 `matplotlib` is **not** a hard dependency. Install it in the same environment only if you
@@ -62,9 +69,15 @@ plan to use the [`_matplotfig`](#block-matplotfig) block.
 ## Live preview (optional)
 
 The [`ym live`](reference/cli.md#ym-live) command opens the rendered PDF in the
-[Okular](https://okular.kde.org/) document viewer and hot-reloads it on every save. If you
+[Okular](https://okular.kde.org/) document viewer which hot-reloads your PDF on every save. 
+
+The Okular PDF viewer is available for _every_ desktop platform (Windows, Mac, and many flavours of Linux).
+
+If you
 want to use live mode, install Okular through your system package manager, for example:
 
 ```bash
 sudo apt install okular      # Debian / Ubuntu
 ```
+
+If you are on Windows, you can install Okular with Winget or with the Windows store.

docs/quickstart.md

@@ -4,8 +4,12 @@ This walkthrough takes you from an empty folder to a rendered PDF.
 
 ## 1. Write a report
 
-Create a file called `report.yml`. The **top-level keys are your headings**, and their
-values are the content underneath them.
+Create a file called `report.yml` (or, you know, something meaningful to you).
+
+The **top-level keys are your headings**, and their
+values are the content (paragraphs or otherwise) underneath them.
+
+See the example below:
 
 ```yaml
 Site inspection report:
@@ -53,6 +57,8 @@ destination:
 ym convert report.yml output/inspection.pdf
 ```
 
+The output directory(ies) will be created if the do not already exist.
+
 ## 3. Iterate live (optional)
 
 While drafting, run [`ym live`](reference/cli.md#ym-live) to open the PDF and rebuild it
@@ -63,7 +69,7 @@ ym live report.yml
 ```
 
 Leave it running in a terminal, edit `report.yml` in your editor, and the preview refreshes
-on save. Press `Ctrl+C` to stop.
+on save. Press `Ctrl+C` to stop (which will also close the attached Okular instance).
 
 ## 4. Style it
 

docs/reference/blocks.md

@@ -7,7 +7,8 @@ others extend it (admonitions, styled horizontal rules, executable Python).
 ## Block syntax
 
 A block is a **key that begins with an underscore**, e.g. `_img` or `_spacer`. Its value is
-a block-specific data structure — sometimes a scalar, sometimes a mapping of parameters.
+a block-specific data structure, typically either a scalar or a mapping that allows several arguments to be passed.
+
 Blocks appear wherever content is allowed, typically as list items:
 
 ```yaml
@@ -20,23 +21,25 @@ Report:
   - _pagebreak:
 ```
 
-Some block codes accept a **suffix** after the underscore code, e.g. `_hrule_red` and
+All block codes accept an optional, user-defined **suffix** after the underscore code, e.g. `_hrule_red` and
 `_hrule_blue` are both handled by the `_hrule` block — the suffix simply keeps the YAML keys
-unique when you use several in one list.
+unique when you use several in one list and allows you to meaningfully identify them if you are using several in a row.
+
+The suffix does not affect how the block is executed. It is simply an optional identifier.
 
 ## Block catalogue
 
 | Block | Purpose |
 | --- | --- |
-| [`_img`](#block-img) | Embed an image with a caption. |
-| [`_matplotfig`](#block-matplotfig) | Embed a matplotlib figure object. |
+| [`_img`](#block-img) | Embed an image with an optional caption. |
+| [`_matplotfig`](#block-matplotfig) | Embed a matplotlib figure object with an optional caption. |
 | [`_info` / `_warning` / `_danger` / `_tip` / `_note`](#block-admonitions) | Callout boxes. |
 | [`_blockquote`](#block-blockquote) | A quotation with attribution. |
-| [`_code`](#block-code) | A non-executable, syntax-highlighted code block. |
-| [`_py`](#block-py) | Execute Python and optionally show the source. |
-| [`_loadjson`](#block-loadjson) | Load variables from a JSON file. |
+| [`_code`](#block-code) | A non-executable code block. |
+| [`_py`](#block-py) | Execute Python and optionally show the syntax-highlighted source. |
+| [`_loadjson`](#block-loadjson) | Load variables into the document from a JSON file. |
 | [`_pagebreak`](#block-pagebreak) | Force a page break. |
-| [`_hrule`](#block-hrule) | A configurable horizontal rule. |
+| [`_hrule`](#block-hrule) | A customizable horizontal rule. |
 | [`_spacer`](#block-spacer) | Insert vertical whitespace. |
 
 ---
@@ -86,7 +89,7 @@ Report:
 | --- | --- | --- | --- |
 | `fig` | ✅ | — | A matplotlib `Figure`, passed as `$var`. |
 | `caption` | | `""` | Caption text shown below the figure. |
-| `scale_ratio` | | `0.8` | Scale factor relative to the available content width. |
+| `scale_ratio` | | `0.8` | Scale factor relative to the available content width. The figure image is automatically shrunk to fit the frame if it would overflow.|
 
 :::{note}
 `matplotlib` is an optional dependency — install it in the same environment as YMPrint to
@@ -141,7 +144,7 @@ _blockquote:
 (block-code)=
 ## `_code` — Preformatted code
 
-A **non-executable**, syntax-highlighted code block. Use this to display code or config
+A **non-executable**, code block for pre-formatted text. Use this to display code or config
 verbatim.
 
 ```yaml
@@ -157,6 +160,9 @@ _code:
 | Parameter | Required | Meaning |
 | --- | --- | --- |
 | `source` | ✅ | The literal text to display. Use a YAML block scalar (`|`) to preserve line breaks. |
+| `line_numbers` | | — | Show line numbers alongside the rendered source. |
+| `caption` | | — | Caption shown with the rendered code. |
+| `width_ratio` | | `0.75` | Width of the rendered code block relative to the content width. |
 
 To **run** code instead of just showing it, use [`_py`](#block-py).
 
@@ -183,6 +189,14 @@ _py:
     c = math.sin(a / b)
 ```
 
+:::{note}
+The `|` after `source:` tells the YAML parser that this is preformatted text, to respect the line breaks exactly as written, and that text should not be wrapped. 
+
+This is in contrast to the `>` character, often used when writing paragraph content, which allows you to break lines wherever you want in the YAML without breaking lines in the finished document.
+
+Both the `|` and `>` character are part of the YAML spec.
+:::
+
 | Parameter | Required | Default | Meaning |
 | --- | --- | --- | --- |
 | `source` | ✅ | — | Python source to execute. |
@@ -194,7 +208,9 @@ _py:
 
 :::{warning}
 `_py` runs `exec()` in the **same** Python environment as YMPrint. External subprocess
-isolation is not currently implemented — only run documents you trust.
+isolation is not currently implemented. Only run documents you trust.
+
+YMPrint is **not** intended to be operated as a public-facing web app.
 :::
 
 After execution the variables are usable everywhere:
@@ -292,5 +308,9 @@ Report:
   - There is a 20 pt spacer above.
 ```
 
-The value is the height of the space in points. A `_spacer: 0` is a handy trick to stop a
+The value is the height of the space in points. 
+
+:::{tip}
+A `_spacer: 0` is a handy trick to stop a
 paragraph being misinterpreted as a bullet when it's immediately followed by a list.
+:::

docs/reference/cli.md

@@ -9,7 +9,7 @@ ym --help
 | Command | What it does |
 | --- | --- |
 | [`ym convert`](#ym-convert) | Render a YAML file to a PDF once. |
-| [`ym live`](#ym-live) | Render, open the PDF, and hot-reload on every save. |
+| [`ym live`](#ym-live) | Render, open the PDF in Okular, which will hot-reload on every save. |
 
 ## `ym convert`
 
@@ -23,7 +23,7 @@ ym convert SRC [DEST] [--config-dir DIR]
 | --- | --- | --- |
 | `SRC` | ✅ | Path to the source YAML report. |
 | `DEST` | | Output PDF path. Defaults to the source path with a `.pdf` extension, written next to the source file. |
-| `--config-dir` | | Directory holding a project config file. If omitted, YMPrint searches parent directories for one. |
+| `--config-dir` | | Directory holding a project config file. If omitted, YMPrint searches parent directories for one. If a config file is not found in the parent directories, the internal default configuration will take priority. |
 
 **Examples**
 
@@ -47,7 +47,9 @@ On success it prints the resolved output path:
 ## `ym live`
 
 Render the PDF, open it in the [Okular](https://okular.kde.org/) viewer, and rebuild
-automatically whenever the source (or a watched config file) changes. Ideal for drafting.
+automatically whenever the source (or the non-default config file) changes.
+
+Ideal for live authoring.
 
 ```bash
 ym live SRC [DEST] [--config-dir DIR]
@@ -60,7 +62,7 @@ ym live SRC [DEST] [--config-dir DIR]
 | `--config-dir` | | Directory of config files to also watch for changes. |
 
 **What it watches.** Live mode watches the source file and, if a config directory is in
-play, the config files within it (`doctemplate.yml`, `textstyles.yml`, `tablestyles.yml`).
+play, the config files within it (`config.ymprint.yml`.
 When any of them changes, the PDF is re-rendered and Okular refreshes.
 
 ```bash
@@ -82,7 +84,7 @@ example `sudo apt install okular` on Debian/Ubuntu). See
 ## Config discovery
 
 When you don't pass `--config-dir`, YMPrint walks **up** from the current working directory
-looking for a config file (a `*.ymprint.yml` project config, or the individual
-`doctemplate.yml` / `textstyles.yml` / `tablestyles.yml` files). The nearest match is used.
-This lets a whole tree of documents share one project style. See
+looking for a config file (a `*.ymprint.yml` project config). The nearest match is used.
+
+This enables a whole tree of documents to share one project style. See
 [Configuration](../guide/configuration.md).

docs/reference/fonts.md

@@ -1,6 +1,6 @@
 # Fonts reference
 
-YMPrint **bundles** a set of font families so your documents render identically on any
+YMPrint **bundles** a select set of font families so your documents render identically on any
 machine — no system font installation required. Reference a family by name in
 [`_style`](#cfg-style).
 
@@ -16,7 +16,7 @@ _style:
 
 The name is the family name (case-sensitive). Each bundled family ships with regular, bold,
 italic, and bold-italic variants, so **bold** and *italic* inline formatting render
-correctly.
+correctly. 
 
 ## Bundled families
 
@@ -38,13 +38,15 @@ correctly.
 
 ## Standard PDF fonts
 
-The built-in defaults also use the standard PDF core fonts such as `Helvetica`, which are
+The built-in defaults also use the standard PDF core fonts (Helvetica, Times, and Courier), which are
 always available. You can name them directly:
 
 ```yaml
 _style:
   body:
     font: Helvetica
+  headings:
+    font: Times 
 ```
 
 ## Inline code font