docx/comment

Metadata

XPath assertions

Render assertions

Generator source

scripts/gen_comment.py

#!/usr/bin/env python3
"""Generate ``fixtures/docx/comment.docx``.

A minimal document exercising the review-comment infrastructure:
``w:commentRangeStart`` / ``w:commentRangeEnd`` markers around a run
in the main story plus a matching ``<w:comment>`` entry with
``@w:author='Reviewer'`` in ``word/comments.xml``.

Uses the fork's ``Document.add_comment(runs=..., text=..., author=...,
initials=...)`` API (python-docx >= 2026.05.0). ``add_comment`` takes
the anchor-range's runs (single run accepted), adds the comment to
the comments part, and emits the comment-range markers + comment
reference automatically.
"""

from __future__ import annotations

import datetime as dt
from pathlib import Path

from docx import Document

_REPO_ROOT = Path(__file__).resolve().parent.parent
_OUT = _REPO_ROOT / "fixtures" / "docx" / "comment.docx"

# Fixed date so the comment's w:date attribute doesn't churn on re-save.
# Without this, add_comment defaults to datetime.now(UTC) which makes
# the fixture non-reproducible even with reproducible=True on save.
_FIXED_DATE = dt.datetime(2026, 5, 4, 0, 0, 0, tzinfo=dt.timezone.utc)


def main() -> int:
    doc = Document()
    paragraph = doc.add_paragraph("Commented paragraph")
    comment = doc.add_comment(
        runs=paragraph.runs,
        text="This is the comment",
        author="Reviewer",
        initials="R",
        date=_FIXED_DATE,
    )
    # w16cid:paraId is still minted non-deterministically — python-docx
    # doesn't yet stamp it under reproducible=True. Pin it by hand so
    # the fixture is byte-stable.
    from docx.oxml.ns import qn
    comment._element.set(qn("w16cid:paraId"), "00000001")
    _OUT.parent.mkdir(parents=True, exist_ok=True)
    doc.save(_OUT, reproducible=True)
    print(_OUT)
    return 0


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

Manifest (expanded)

{
  "$schema": "../manifest.schema.json",
  "id": "docx/comment",
  "title": "Review comment",
  "format": "docx",
  "category": "review",
  "summary": "A comment authored by 'Reviewer' is attached to a run via matched commentRangeStart/End markers, with the comment body stored in word/comments.xml.",
  "spec": {
    "source": "ecma-376-5-part-1",
    "clause": "17.13.4",
    "element": "w:comment",
    "rnc_reference": "spec/ecma-376-5/part-1/rnc/WordprocessingML.rnc",
    "xsd_reference": "spec/ecma-376-5/part-1/xsd/wml.xsd",
    "notes": "A comment is split across parts: <w:commentRangeStart>/<w:commentRangeEnd> markers delimit the referenced run range in the main story, a <w:commentReference> sits inside an adjacent run, and the actual <w:comment> body — including @w:author, @w:initials, @w:date — lives in word/comments.xml."
  },
  "fixtures": {
    "machine": "docx/comment",
    "office": "docx/comment"
  },
  "generator": {
    "python": "scripts/gen_comment.py"
  },
  "assertions": [
    {
      "id": "comment-range-start-in-body",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:commentRangeStart[@w:id]",
      "must": "exist",
      "description": "A <w:commentRangeStart> must mark the beginning of the commented range in the main document."
    },
    {
      "id": "comment-body-by-author",
      "part": "word/comments.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:comment[@w:author='Reviewer']/w:p/w:r/w:t[normalize-space()='This is the comment']",
      "must": "exist",
      "description": "The comments part must contain a <w:comment> authored by 'Reviewer' whose body text is the fixture literal."
    }
  ],
  "render_assertions": [
    {
      "id": "comment-anchor-rendered",
      "kind": "css_selector",
      "selector": ".docx-wrapper .comment, .docx-wrapper [data-comment], .docx-wrapper .comment-reference",
      "must": "exist",
      "description": "Some marker for the comment should exist in the rendered DOM. Many renderers drop review comments — this is a known gap to track."
    }
  ]
}