docx/paragraph-spacing

Parameter axes

• before (3 values): none, small, large
• after (3 values): none, small, large

Spec notes

Generator source

scripts/gen_paragraph_spacing.py — runs with --arg_template --before {before.pt} --after {after.pt} --out fixtures/docx/paragraph-spacing--{after.id}--{before.id}.docx

#!/usr/bin/env python3
"""Generate a ``fixtures/docx/paragraph-spacing--<after>--<before>.docx`` fixture.

Parameterised generator for the ``docx/paragraph-spacing`` feature family.
One invocation writes a single fixture for the given before/after spacing
pair (both expressed in points).

Usage::

    python scripts/gen_paragraph_spacing.py \
        --before 6 \
        --after 18 \
        --out fixtures/docx/paragraph-spacing--large--small.docx

``--before`` and ``--after`` are integer points; the python-docx
``Pt()`` helper converts them to the twentieths-of-a-point unit that
``<w:spacing w:before/w:after>`` expects (1pt = 20 twips). python-docx
emits the attributes explicitly even when the value is 0, so the
``none`` / ``none`` case still produces ``w:before="0" w:after="0"``
rather than dropping the attributes.

See ECMA-376-5 Part 1 clause 17.3.1.33.
"""

from __future__ import annotations

import argparse
from pathlib import Path

from docx import Document
from docx.shared import Pt

_REPO_ROOT = Path(__file__).resolve().parent.parent


def _write(before_pt: int, after_pt: int, out: Path) -> None:
    doc = Document()
    paragraph = doc.add_paragraph("Spaced paragraph")
    paragraph_format = paragraph.paragraph_format
    paragraph_format.space_before = Pt(before_pt)
    paragraph_format.space_after = Pt(after_pt)
    out.parent.mkdir(parents=True, exist_ok=True)
    doc.save(out, reproducible=True)


def main() -> int:
    parser = argparse.ArgumentParser()
    parser.add_argument(
        "--before",
        type=int,
        required=True,
        help="Space before the paragraph, in points.",
    )
    parser.add_argument(
        "--after",
        type=int,
        required=True,
        help="Space after the paragraph, in points.",
    )
    parser.add_argument(
        "--out",
        required=True,
        help="Repo-relative or absolute output path for the .docx.",
    )
    args = parser.parse_args()

    out_path = Path(args.out)
    if not out_path.is_absolute():
        out_path = _REPO_ROOT / out_path
    _write(args.before, args.after, out_path)
    print(out_path)
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

Manifest (parent, unexpanded)

{
  "$schema": "../manifest.schema.json",
  "id": "docx/paragraph-spacing",
  "kind": "parameterised",
  "title": "Paragraph spacing (before/after)",
  "format": "docx",
  "category": "paragraph-layout",
  "summary": "Paragraph spacing before and after — <w:spacing w:before=\"...\" w:after=\"...\"/> inside <w:pPr>, exercised across 3 before values x 3 after values (0 / 6pt / 18pt).",
  "spec": {
    "source": "ecma-376-5-part-1",
    "clause": "17.3.1.33",
    "element": "w:spacing",
    "rnc_reference": "spec/ecma-376-5/part-1/rnc/WordprocessingML.rnc",
    "xsd_reference": "spec/ecma-376-5/part-1/xsd/wml.xsd",
    "notes": "Paragraph spacing is carried by <w:spacing> inside <w:pPr>. The @w:before / @w:after attributes are expressed in twentieths of a point (twips): 120 = 6pt, 360 = 18pt. This parameterised manifest covers 3 before values x 3 after values = 9 cases. python-docx emits @w:before / @w:after explicitly even when the value is 0, so the equality assertions hold unconditionally for all 9 cases."
  },
  "fixtures": {
    "machine": "docx/paragraph-spacing"
  },
  "generator": {
    "python": "scripts/gen_paragraph_spacing.py",
    "arg_template": "--before {before.pt} --after {after.pt} --out fixtures/docx/paragraph-spacing--{after.id}--{before.id}.docx"
  },
  "parameters": {
    "before": [
      {
        "id": "none",
        "pt": 0,
        "twips": 0
      },
      {
        "id": "small",
        "pt": 6,
        "twips": 120
      },
      {
        "id": "large",
        "pt": 18,
        "twips": 360
      }
    ],
    "after": [
      {
        "id": "none",
        "pt": 0,
        "twips": 0
      },
      {
        "id": "small",
        "pt": 6,
        "twips": 120
      },
      {
        "id": "large",
        "pt": 18,
        "twips": 360
      }
    ]
  },
  "assertions_template": [
    {
      "id": "spacing-before-{before.id}-after-{after.id}",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:p[w:r/w:t[normalize-space()='Spaced paragraph']]/w:pPr/w:spacing/@w:before",
      "must": "match",
      "value": "^{before.twips}$",
      "description": "w:spacing@w:before must be {before.twips} twips ({before.pt}pt) for this case."
    }
  ],
  "render_assertions_template": [
    {
      "id": "visual-matches-libreoffice-render",
      "kind": "visual_ssim",
      "min_ssim": 0.5,
      "description": "Playwright screenshot of the rendered output must score >=85% SSIM against the LibreOffice-rendered reference PNG."
    }
  ]
}