docx_plus.publishing.figures

Table of Figures via the TOC \c "<caption_type>" complex field. Structurally identical to a Table of Contents but driven by SEQ caption names instead of paragraph outline levels — the caption_type must match the value passed to docx_plus.publishing.add_caption.

Architecture walkthrough: ARCHITECTURE.md §7.10.

docx_plus.publishing.figures

Table of Figures — TOC \c "Figure" complex field.

A Table of Figures is structurally the same as a Table of Contents, except the field instruction uses the \c "<caption_type>" switch to collect SEQ captions of the named type instead of paragraphs with outline levels. The caption helpers in docx_plus.publishing.captions produce the entries this table picks up.

This module imports only from docx_plus.core (SPEC §9.1).

add_table_of_figures

add_table_of_figures(
    paragraph: Paragraph,
    *,
    caption_type: str = "Figure",
    hyperlink: bool = True,
) -> etree._Element

Append a Table of Figures complex field to paragraph.

The field lists every caption whose SEQ name equals caption_type. Word populates the result on next open; call :func:docx_plus.fields.mark_fields_dirty before saving so the table fills in automatically.

Parameters:

Name	Type	Description	Default
paragraph	Paragraph	A python-docx :class:~docx.text.paragraph.Paragraph where the field is appended.	required
caption_type	str	SEQ name to match — must equal the caption_type passed to :func:docx_plus.publishing.add_caption. Must conform to the SEQ identifier rule (ASCII letter/underscore start, then letters/digits/underscores).	'Figure'
hyperlink	bool	When True (default), entries become clickable hyperlinks via the \h switch.	True

Returns:

Type	Description
_Element	The <w:r> element wrapping the field's begin fldChar.

Raises:

Type	Description
ValueError	If caption_type is empty or violates the SEQ identifier rule (issues.md H11).

Example

from docx import Document from docx_plus.publishing import add_caption, add_table_of_figures from docx_plus.fields import mark_fields_dirty doc = Document() doc.add_paragraph("List of Figures") add_table_of_figures(doc.add_paragraph())

... captions added elsewhere via add_caption(..., caption_type="Figure")

mark_fields_dirty(doc)

Source code in docx_plus/publishing/figures.py

def add_table_of_figures(
    paragraph: Paragraph,
    *,
    caption_type: str = "Figure",
    hyperlink: bool = True,
) -> etree._Element:
    r"""Append a Table of Figures complex field to ``paragraph``.

    The field lists every caption whose ``SEQ`` name equals
    ``caption_type``. Word populates the result on next open; call
    :func:`docx_plus.fields.mark_fields_dirty` before saving so the
    table fills in automatically.

    Args:
        paragraph: A python-docx :class:`~docx.text.paragraph.Paragraph`
            where the field is appended.
        caption_type: ``SEQ`` name to match — must equal the
            ``caption_type`` passed to
            :func:`docx_plus.publishing.add_caption`. Must conform to
            the SEQ identifier rule (ASCII letter/underscore start,
            then letters/digits/underscores).
        hyperlink: When ``True`` (default), entries become clickable
            hyperlinks via the ``\h`` switch.

    Returns:
        The ``<w:r>`` element wrapping the field's ``begin`` ``fldChar``.

    Raises:
        ValueError: If ``caption_type`` is empty or violates the SEQ
            identifier rule (issues.md H11).

    Example:
        >>> from docx import Document
        >>> from docx_plus.publishing import add_caption, add_table_of_figures
        >>> from docx_plus.fields import mark_fields_dirty
        >>> doc = Document()
        >>> doc.add_paragraph("List of Figures")
        >>> add_table_of_figures(doc.add_paragraph())
        >>> # ... captions added elsewhere via add_caption(..., caption_type="Figure")
        >>> mark_fields_dirty(doc)
    """
    validate_seq_identifier(caption_type, arg_name="caption_type")

    # Assemble the switches as a list so the conditional `\h` reads at a
    # glance (N2); `\z` hides tab/page-number leaders in the web view.
    switches = [f'TOC \\c "{caption_type}"']
    if hyperlink:
        switches.append("\\h")
    switches.append("\\z")
    instruction = f" {' '.join(switches)} "
    return build_complex_field(paragraph._p, instruction, "")