docx_mastery

Files (1)

• SKILL.md

SKILL.md (first lines)

# Professional DOCX Engineering with Python

This skill teaches how to design and generate executive-grade, publication-ready Word documents (`.docx`), as well as safely edit and annotate existing `.docx` files using Python.

---

## 🎨 Part 1: High-Level Document Design & Typographic Principles

A well-crafted Word document communicates authority, clarity, and visual hierarchy before a single word is read.

### 1. Typography & Hierarchy
* **Primary / Body Font**: Use clean, modern serifs or sans-serifs (e.g., `Calibri`, `Aptos`, `Arial`, `Segoe UI`, or `Georgia` / `Garamond` for formal reports).
* **Headings**: Complementary font with distinct weight and color (e.g., Navy `#1F4E79` or Slate `#2B3E50`).
* **Scale Guideline**:
  - Title: `24–28 pt`, Bold
  - Subtitle: `14–16 pt`, Regular or Italic, Muted Gray (`#595959`)
  - Heading 1: `18–20 pt`, Bold, Colored
  - Heading 2: `14–16 pt`, Semi-bold
  - Heading 3: `12–13 pt`, Medium / Bold
  - Body: `10.5–11.5 pt`, Line spacing `1.15–1.25`, Space after `4–6 pt`.

### 2. Palette & Theme Consistency
Always define a coherent 4-color palette for the document:
- **Primary Accent**: Main brand color (e.g., Deep Blue `#1B365D`) for H1s, table header fills, callout left-bars.
- **Secondary Accent**: Secondary color (e.g., Teal `#008080` or Steel Blue `#4A90E2`) for H2s, table highlights.
- **Neutral Dark**: Main text body (e.g., Charcoal `#262626`, never pure `#000000` for eye comfort).
- **Neutral Light**: Backgrounds for callout boxes and alternating table rows (e.g., Warm White / Soft Gray `#F2F4F7`).

### 3. Structural Archetypes
1. **Executive Cover Page**: Minimalist or Accent Header Band layout with Title, Subtitle, Author, Organization, Version, and Date.
2. **Callout / Note Boxes**: 1×1 shaded tables with a thick colored left border for warnings, takeaways, or executive summaries.
3. **Publication-Quality Tables**:
   - Header row with primary fill and bold white text.
   - Alternating row shading (`zebra striping`) with `#F9FAFB`.
   - Right-aligned numbers, left-aligned text, centered dates/status badges.
   - Explicit column widths and cell vertical centering.
4. **Header & Footer**:
   - Header: Right-aligned Document Title / Chapter in `8.5 pt` muted gray.
   - Footer: Left-aligned Confidentiality/Copyright, Right-aligned dynamic Page Numbering.

---

## 💻 Part 2: Building Documents from Scratch in Python

### Required Dependency
```bash
pip install python-docx
```

### Complete End-to-End Generator Template

```python
import os
from pathlib import Path
from docx import Document
from docx.shared import Inches, Pt, RGBColor
from docx.enum.text import WD_ALIGN_PARAGRAPH
from docx.enum.table import WD_TABLE_ALIGNMENT, WD_ALIGN_VERTICAL
from docx.oxml import OxmlElement, parse_xml
from docx.oxml.ns import nsdecls, qn

def set_cell_background(cell, hex_color: str):
    """Sets background fill color of a table cell."""
    tcPr = cell._element.get_or_add_tcPr()
    shd = parse_xml(f'<w:shd {nsdecls("w")} w:fill="{hex_color.replace("#", "")}"/>')
    tcPr.append(shd)

def set_cell_margins(cell, top=100, bottom=100, left=150, right=150):
    """Sets internal padding (in twips) for a table cell."""
    tcPr = cell._element.get_or_add_tcPr()
    tcMar = OxmlElement('w:tcMar')
    for m, val in [('top', top), ('bottom', bottom), ('left', left), ('right', right)]:
        node = OxmlElement(f'w:{m}')
        node.set(qn('w:w'), str(val))
        node.set(qn('w:type'), 'dxa')
        tcMar.append(node)
    tcPr.append(tcMar)

def set_cell_left_border_only(cell, hex_color: str, size: int = 24):
    """Sets a thick colored left border and removes top/bottom/right borders (for Callout Boxes)."""
    tcPr = cell._element.get_or_add_tcPr()
    tcBorders = parse_xml(f'''
        <w:tcBorders {nsdecls("w")}>
            <w:top w:val="none"/>
            <w:left w:val="single" w:sz="{size}" w:space="0" w:color="{hex_color.replace("#", "")}"/>
            <w:bottom w:val="none"/>
            <w:right w:val="none"/>
        </w:tcBorders>
    ''')
    tcPr.append(tcBorders)

def add_page_number(run):
    """Inserts a dynamic Word PAGE field."""
    fldSimple = OxmlElement('w:fldSimple')
    fldSimple.set(qn('w:instr'), 'PAGE')
    run._r.append(fldSimple)

def create_styled_document(output_path: str = "report.docx"):
    doc = Document()

    # 1. Page Margins
    for section in doc.sections:
        section.top_margin = Inches(1.0)
        section.bottom_margin = Inches(1.0)
        section.left_margin = Inches(1.0)
        section.right_margin = Inches(1.0)
        
        # Enable different first page for clean cover page
        section.different_first_page_header_footer = True
        
        # Header / Footer setup
        footer = section.footer
        f_p = footer.paragraphs[0]
        f_p.alignment = WD_ALIGN_PARAGRAPH.RIGHT
        f_run = f_p.add_run("Page ")
        f_run.font.size = Pt(9)
        f_run.font.color.rgb = RGBColor(128, 128, 128)
        add_page_number(f_run)

From ParisNeo/lollms_client, Apache-2.0.

More from ParisNeo/lollms_client