docx/field-toc

Metadata

XPath assertions

Render assertions

Generator source

scripts/gen_field_toc.py

#!/usr/bin/env python3
"""Generate ``fixtures/docx/field-toc.docx``.

A document with two ``Heading 1`` paragraphs and a TOC complex field
hoisted to the top of the body. Uses the fork's high-level
``Document.add_table_of_contents(levels=(1, 3))`` helper; the resulting
field is a ``w:fldChar begin/separate/end`` triple wrapping a
``w:instrText`` with ``TOC \\o "1-3" \\h \\z \\u``.
"""

from __future__ import annotations

from pathlib import Path

from docx import Document

_REPO_ROOT = Path(__file__).resolve().parent.parent
_OUT = _REPO_ROOT / "fixtures" / "docx" / "field-toc.docx"


def main() -> int:
    doc = Document()
    # -- Seed the body with real headings before the TOC is populated, so
    #    the cached TOC result text can preview them. --
    doc.add_heading("First heading", level=1)
    doc.add_paragraph("Body of first section.")
    doc.add_heading("Second heading", level=1)
    doc.add_paragraph("Body of second section.")

    # -- Append the TOC (it snapshots the headings above, not itself). --
    doc.add_table_of_contents(levels=(1, 3))

    # -- Move the newly-appended TOC paragraph to the top of the body,
    #    where a real document would place it. --
    body = doc.element.body
    toc_p = doc.paragraphs[-1]._p
    body.remove(toc_p)
    body.insert(0, toc_p)

    _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/field-toc",
  "title": "Field: TOC (table of contents)",
  "format": "docx",
  "category": "fields",
  "summary": "A table-of-contents complex field at the top of the body, generated from heading-level paragraphs.",
  "spec": {
    "source": "ecma-376-5-part-1",
    "clause": "17.16.5",
    "element": "w:instrText",
    "rnc_reference": "spec/ecma-376-5/part-1/rnc/WordprocessingML.rnc",
    "xsd_reference": "spec/ecma-376-5/part-1/xsd/wml.xsd",
    "notes": "python-docx emits TOC as a complex field (w:fldChar begin/separate/end with a w:instrText carrying 'TOC \\o \"1-3\" \\h \\z \\u'), not a simple <w:fldSimple>. The cached result text in the separate/end block previews the headings so non-Word viewers show something sensible; Word rebuilds the real TOC on open."
  },
  "fixtures": {
    "machine": "docx/field-toc",
    "office": "docx/field-toc"
  },
  "generator": {
    "python": "scripts/gen_field_toc.py"
  },
  "assertions": [
    {
      "id": "toc-instrText-present",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:instrText[contains(normalize-space(), 'TOC')]",
      "must": "exist",
      "description": "A <w:instrText> carrying a TOC instruction must be present (complex-field form)."
    },
    {
      "id": "toc-fldChar-begin-present",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:fldChar[@w:fldCharType='begin']",
      "must": "exist",
      "description": "The document must contain at least one <w:fldChar w:fldCharType='begin'> marker (the start of the TOC's complex field)."
    },
    {
      "id": "toc-has-headings",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:p/w:pPr/w:pStyle[starts-with(@w:val, 'Heading')]",
      "must": "exist",
      "description": "The document must include at least one Heading-styled paragraph for the TOC to reference."
    }
  ],
  "render_assertions": [
    {
      "id": "toc-rendered",
      "kind": "css_selector",
      "selector": ".docx-wrapper .toc, .docx-wrapper [data-field='TOC'], .docx-wrapper p",
      "must": "match-text",
      "value": "(First heading|Second heading)",
      "description": "A renderer-exposed TOC (or the fallback paragraph) must surface at least one of the source heading labels, typically via the cached TOC result text."
    }
  ]
}