Schopenhauer's Will

The Will to Document
A powerful CLI tool and Python library for generating Word documents from YAML/JSON specifications

Documentation • Installation • Quick Start • Features • API

Overview

Schopenhauer transforms YAML or JSON specifications into professional Word documents (.docx). Named after the philosopher Arthur Schopenhauer and his work "The World as Will and Representation," this tool embodies the will to create beautiful documents programmatically.

Why Schopenhauer?

• Version Control Friendly: Document specs are plain text (YAML/JSON)
• Reproducible: Same spec always produces the same output
• Automatable: Perfect for CI/CD pipelines and batch processing
• Customizable: Full control over styling, templates, and content
• Cloud Ready: REST API for microservices and cloud deployment

Installation

pip install schopenhauer

Optional Dependencies

# With REST API server
pip install schopenhauer[api]

# With documentation tools
pip install schopenhauer[docs]

# Everything
pip install schopenhauer[all]

Quick Start

CLI Usage

# Create a simple document
will create -o report.docx --title "Annual Report" --author "Jane Doe"

# Generate from YAML specification
will generate spec.yaml -o output.docx

# Initialize a YAML template
will template init report -o my-report.yaml

# Interactive document creation
will new -o document.docx

YAML Specification

Create a file report.yaml:

title: Quarterly Report
subtitle: Q4 2024 Results
author: Analytics Team

page_size: letter
margins: moderate
table_of_contents: true

sections:
  - type: section
    title: Executive Summary

  - type: content
    text: |
      This report summarizes the key achievements
      and metrics for the fourth quarter.

  - type: content
    title: Key Highlights
    bullets:
      - Revenue increased by 25%
      - Customer satisfaction at all-time high
      - New product launch successful

  - type: table
    title: Performance Metrics
    headers: [Metric, Q3, Q4, Change]
    data:
      - [Revenue, "$1.2M", "$1.5M", "+25%"]
      - [Users, "10K", "15K", "+50%"]

Generate the document:

will generate report.yaml -o quarterly-report.docx

Python API

from will import WordDocument, DocumentBuilder

# Simple approach
doc = WordDocument()
doc.add_title("My Report", subtitle="2024 Edition")
doc.add_heading("Introduction", level=1)
doc.add_paragraph("Welcome to the report.")
doc.add_bullets(["Point 1", "Point 2", "Point 3"])
doc.add_table(
    data=[["Alice", "Engineering"], ["Bob", "Sales"]],
    headers=["Name", "Department"]
)
doc.save("report.docx")

# Fluent builder approach
(DocumentBuilder()
    .set_title("My Report")
    .add_heading("Introduction")
    .add_paragraph("Welcome to the report.")
    .add_bullets(["Point 1", "Point 2"])
    .save("report.docx"))

Features

Content Types

• Headings: Multiple levels (H1-H5) with custom styling
• Paragraphs: Rich text with formatting options
• Lists: Bullet and numbered lists with nesting
• Tables: Data tables with headers and styling
• Images: Inline images with captions
• Quotes: Blockquotes with attribution
• Code Blocks: Formatted code snippets
• Page Breaks: Manual page control
• Table of Contents: Automatic TOC generation

Document Features

• Templates: Built-in templates for reports, memos, proposals, etc.
• Placeholders: {{PLACEHOLDER}} syntax for dynamic content
• Headers/Footers: Configurable with page numbers
• Page Setup: Custom sizes, margins, orientation
• Styling: Brand colors, fonts, and formatting

Deployment Options

• CLI Tool: will command for terminal usage
• Python Library: Full API for programmatic use
• REST API: FastAPI server for cloud deployment
• Docker: Containerized deployment
• GCP Cloud Run: One-click deployment script

CLI Commands

Templates

Built-in templates for common document types:

• default - Clean, professional default
• report - Business report with header/footer
• memo - Internal memo format
• letter - Formal business letter
• academic - Academic paper (APA-style)
• proposal - Project proposal
• manual - Technical documentation
• contract - Legal contract format
• And more...

# List templates
will template list

# Use a template
will create -o doc.docx --template report --title "Report"

# Initialize YAML from template
will template init proposal -o my-proposal.yaml

REST API

Deploy as a REST API for cloud-based document generation:

# Start the server
uvicorn will.api:app --host 0.0.0.0 --port 8000

# Or with Docker
docker build -t schopenhauer .
docker run -p 8000:8000 schopenhauer

Endpoints

Example Request

curl -X POST "http://localhost:8000/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Report",
    "sections": [
      {"type": "heading", "title": "Introduction", "level": 1},
      {"type": "content", "text": "Hello, World!"}
    ]
  }' \
  --output report.docx

Cloud Deployment

GCP Cloud Run

# Deploy to Cloud Run
./deploy.sh --project my-project --region us-central1

# Build only
./deploy.sh --build-only --local

Docker

# Build image
docker build -t schopenhauer .

# Run container
docker run -p 8000:8000 schopenhauer

# Access API
curl http://localhost:8000/health

Documentation

Full documentation is available at schopenhauer.github.io/schopenhauer.

Building Docs Locally

pip install schopenhauer[docs]
mkdocs serve

Development

Setup

# Clone repository
git clone https://github.com/schopenhauer/schopenhauer.git
cd schopenhauer

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Run linters
black src tests
ruff check src tests
mypy src

Running Tests

# All tests
pytest

# With coverage
pytest --cov=will --cov-report=html

# Specific test file
pytest tests/test_core.py

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Named after Arthur Schopenhauer (1788-1860), German philosopher
• Built with python-docx
• CLI powered by Click
• API built with FastAPI

_{The Will to Document
Made with ♥ by the Schopenhauer Contributors}