v0.1.1 · MIT Licensed

Define. Structure.
Document.

A powerful Python toolkit for generating Word documents. Define structure in YAML, generate professional DOCX files with templates, styles, and full automation.

Get Started GitHub Documentation
W
$ pip install schopenhauer

Features

Everything You Need

A complete toolkit for generating professional Word documents from structured specifications.

YAML/JSON Specification

Define your entire document structure in YAML or JSON. Headings, paragraphs, tables, images, and more—all declaratively specified.

15+ Built-in Templates

Start with professional templates: reports, memos, letters, proposals, academic papers, contracts, resumes, and more.

Variable Substitution

Use {{PLACEHOLDERS}} for dynamic content. Pass variables via CLI or Python API to generate personalized documents.

Rich Formatting

Support for bold, italic, underline, code blocks, block quotes, bullet points, numbered lists, and custom styles.

Images & Tables

Embed images from local files or URLs. Create tables with headers, custom column widths, and styling options.

Python API

Fluent builder API for programmatic document generation. Chain methods for intuitive document construction.

REST API

Deploy as a microservice with FastAPI. Generate documents via HTTP endpoints, perfect for cloud integration.

Cloud Ready

Docker support and GCP Cloud Run deployment script included. Scale document generation effortlessly.

Quick Start

Simple by Design

Get started in seconds. Define your document in YAML, generate with one command.

# Define your document structure
title: "Quarterly Report"
template: report

content:
  - type: heading
    level: 1
    text: "Executive Summary"

  - type: paragraph
    text: "This report covers Q4 {{YEAR}} performance..."

  - type: table
    headers: ["Metric", "Value", "Change"]
    rows:
      - ["Revenue", "$1.2M", "+15%"]
      - ["Users", "50,000", "+22%"]

  - type: image
    path: "./charts/revenue.png"
    width: 5
# Generate the document
$ will generate document.yaml -o report.docx --var YEAR=2024
Generated document: report.docx

# Or use Python
from will import WordDocument

doc = WordDocument.from_yaml("document.yaml")
doc.replace_placeholders({"YEAR": "2024"})
doc.save("report.docx")

CLI Reference

The will Command

A powerful command-line interface for all your document generation needs.

will create Interactively create a new document. Prompts for title, template, and content type to get you started quickly.
will generate Generate a DOCX from YAML/JSON specification. Options: -o output.docx, --var KEY=VALUE for variable substitution.
will inspect Inspect an existing DOCX file. Shows document structure, styles, paragraphs, tables, and images.
will template list List all available templates. Shows 15+ built-in templates with descriptions and use cases.
will template info Show detailed information about a specific template including margins, fonts, and page size.
will template init Initialize a new YAML specification from a template. Options: --template report, --output spec.yaml.
will add Add content to an existing document. Add headings, paragraphs, tables, or images to any DOCX file.
will replace Replace placeholders in a document. Batch replace {{VARIABLES}} with actual values.
"
The will is the thing-in-itself... the innermost essence, the kernel, of every particular thing and also of the whole.
— Arthur Schopenhauer, The World as Will and Representation

Python API

Fluent Builder Pattern

Chain methods for intuitive, readable document construction.

from will import DocumentBuilder

# Create a document with fluent API
doc = (
    DocumentBuilder("report")
    .title("Annual Report 2024")
    .heading("Introduction", level=1)
    .paragraph("This report summarizes our key achievements...")
    .heading("Financial Highlights", level=2)
    .bullets([
        "Revenue increased by 25%",
        "Customer base grew to 100,000",
        "Launched 3 new products"
    ])
    .table(
        headers=["Quarter", "Revenue", "Growth"],
        rows=[
            ["Q1", "$2.1M", "+18%"],
            ["Q2", "$2.4M", "+22%"],
            ["Q3", "$2.8M", "+25%"],
            ["Q4", "$3.2M", "+28%"],
        ]
    )
    .image("./charts/growth.png", width=5)
    .quote("Innovation distinguishes between a leader and a follower.")
    .build()
)

doc.save("annual_report.docx")