gravitas-md2gdocs/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build & Development Commands

# Install for development (using uv)
uv sync --extra dev

# Install with Google API support
uv sync --extra dev --extra google

# Run tests
uv run pytest tests/ -v

# Run tests with coverage
uv run pytest tests/ -v --cov=src/gravitas_md2gdocs

# Run a single test
uv run pytest tests/test_converter.py::TestMarkdownParser::test_parse_header -v

# Lint and format
uv run ruff check .
uv run ruff format .

# Check formatting only
uv run ruff format --check .

# Build package
uv build

Architecture

This library converts Markdown to Google Docs API batchUpdate requests.

Core flow:

1. MarkdownParser (parser.py) parses markdown text into a list of Paragraph objects, each containing TextRun objects with styling info
2. DocsRequestBuilder (converter.py) converts those paragraphs into Google Docs API request dictionaries
3. to_requests() in __init__.py is the main entry point that chains these together

Key classes:

• TextRun: Dataclass holding text with inline styling (bold, italic, code, link, etc.)
• Paragraph: Dataclass holding runs plus paragraph-level info (heading level, list type, blockquote)
• MarkdownParser: Regex-based parser that produces Paragraph lists
• DocsRequestBuilder: Generates insertText, updateTextStyle, updateParagraphStyle, and createParagraphBullets requests

Google API helpers (require gravitas-md2gdocs[google]): append(), replace(), insert_at(), replace_range() wrap the docs service to provide common operations.

Important implementation detail: The builder reverses the request list because Google Docs API applies requests in order and inserting at an index shifts subsequent content.