Add py-doc new, and keep table captions with their table in Word

[markbac]

Summary

py-doc new

Starts one document in the current folder in the legacy build file format, ready for py-doc build --legacy:

• <number>-<Title>.yaml with meta (title, author, version 0.1.0, today's date, description, document_number, classification), cli (emit-docx + output, or a .pptx output) and one entry, plus <number>-<Title>.md starting with the title.
• A wizard asks for the title, type code, Word or PowerPoint, author (default git config user.name), classification and description. Each has an option; -y asks nothing. An existing file is never replaced.

Number register

• doc-numbers.yml at the repository root (found from any folder below it): an optional prefix, an optional start, and documents with only number, title and file.
• A number is [prefix-][type-]NNN; prefix and type are optional, and NNN is one counter for every type.
• The first run makes the register from the document_number of the legacy build files already in the repository, and asks for the prefix.
• Committing the register with the document turns two people taking the same number on separate branches into a merge conflict.

Register upkeep (no document made)

• --scan adds the legacy build files not in the register yet, matched by file, numbers that clash included, and lists each clash. A second scan adds nothing.
• --start N is kept as start: N: new numbers begin at N and skip any number already taken. Without it, the next is one more than the highest.

Table captions stay with their table (Word)

A caption below a table could fall to the top of the next page on its own. Word has no "keep with previous", so keep_captions_with_tables:

• keeps the table's last row (marked not to split) with a caption below it;
• keeps a caption above a table with the table;
• treats a caption between two tables as the next table's, as markers.lua does for HTML and PDF.

It runs after apply_explicit_styles and format_all_tables, so [[CAPTION:]] lines are already Caption paragraphs.

Docs

README command table and layout, the guide's command list, and a "New legacy documents" section in the reference (two sentences shortened to pass Vale's 30-word limit in py-doc lint --strict).

Testing

• tests/test_new.py (13 tests) for py-doc new, the register, --scan and --start; tests/test_logging_policy.py covers new.
• tests/test_word_layout.py: a caption below, a caption between two tables and a caption above, checked in the Word XML (cantSplit and keepNext). It fails on the old code.
• Full suite passes except the 7 tests/test_examples.py failures that also occur on main here (no Graphviz, Mermaid or PlantUML in this environment); ruff check is clean.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Ket2UPXgz46XKSUqpuPixk