latex-builder 0.0.15

A tool for building LaTeX documents with Git integration and diff generation

LaTeX Builder

A Python tool for building LaTeX documents with Git version management and automatic diff generation.

Features

• Git Integration: Automatic detection of current commit, branch, and tag information
• LaTeX Compilation: Complete compilation workflow using XeLaTeX and BibTeX
• Diff Generation: Create visual differences between Git versions using latexdiff
• Version Management: Generate version information files for LaTeX documents
• Clear Logging: Beautiful command-line interface with clear progress indicators
• GoReleaser-like Versioning: Smart version naming based on Git tags and working tree status

Version Naming Logic

The tool uses GoReleaser-like version naming:

• Tag commits: {tag}-{commit} (e.g., v1.2.3-a1b2c3d)
• Non-tag commits: {next_version}-snapshot-{commit} (e.g., v1.2.4-snapshot-a1b2c3d)
• Dirty working tree: {version}-dirty-{commit} (e.g., v1.2.4-dirty-a1b2c3d)

Where {next_version} is the patch-bumped version of the latest semantic version tag.

Usage

Command Line

# Basic usage (in Git repository containing main.tex)
pipx run latex-builder

# Specify LaTeX file
pipx run latex-builder -t document.tex

# Specify output directory
pipx run latex-builder -o build_output

# Enable verbose output
pipx run latex-builder -v

# Full options
pipx run latex-builder -t main.tex -r misc/revision.tex -o output -b build -v

Generate Only revision.tex

# Generate revision.tex only (no build or diff)
pipx run latex-builder revision

# Specify output path for revision.tex
pipx run latex-builder revision --revision-file misc/revision.tex

Python API

from latex_builder import Config, LatexDiffTool
from pathlib import Path

# Create configuration
config = Config(
    tex_file="main.tex",
    revision_path="misc/revision.tex",
    output_folder=Path("output"),
    build_dir=Path("build"),
    verbose=True
)

# Run tool
tool = LatexDiffTool(config)
exit_code = tool.run()

Package Structure

latex_builder/
├── cli/                    # Command line interface
│   ├── main.py            # Main application class
│   └── parser.py          # Command line argument parsing
├── config/                # Configuration management
│   └── settings.py        # Configuration data classes
├── diff/                  # Diff generation
│   └── generator.py       # LaTeX diff operations
├── git/                   # Git operations
│   ├── repository.py      # Git repository handling
│   └── revision.py        # Git version data structures
├── latex/                 # LaTeX processing
│   └── processor.py       # LaTeX compilation
└── utils/                 # Shared utilities
    ├── command.py         # Command execution
    └── logging.py         # Logging setup

Configuration Options

• tex_file: Main LaTeX file to compile (default: "main.tex")
• revision_path: Path to revision.tex file (default: "variables/revision.tex")
• verbose: Enable debug logging (default: False)
• output_folder: Output files directory (default: "output")
• build_dir: Temporary build files directory (default: "build")

Output Files

The tool generates the following output files:

• Current Version PDF: {version-name}.pdf
• Diff Files:
  • LaTeX Source: {compare-version}-vs-{current-version}.tex
  • PDF Document: {compare-version}-vs-{current-version}.pdf
• Metadata: metadata.json containing detailed version information in a nested structure:
  • diff_generation/: Generation settings and timestamp
  • revisions/: Complete information for both current and compare revisions
    • commit/: Hash, summary, message, date
    • author/: Name and email
    • version/: Display name, version name, tag, dirty status
    • git/: Branch and reference information
  • files/: Generated diff file names
  • repository/: Repository and working directory paths
• Version File: revision.tex containing version macros for LaTeX

Examples:

• v1.2.3-a1b2c3d-20241130091545-vs-v1.2.4-snapshot-e4f5g6h-20241201143022.tex
• v1.2.4-snapshot-a1b2c3d-dirty-20241201143022-vs-v1.2.5-e4f5g6h-20241202120000.pdf

The timestamp format is YYYYMMDDHHMMSS in UTC timezone. Version naming follows the pattern:

• Tag versions: {tag}-{commit}-{timestamp}
• Non-tag versions: {next_version}-snapshot-{commit}-{timestamp}
• Dirty versions: {version}-{commit}-dirty-{timestamp}
• Dirty snapshots: {next_version}-snapshot-{commit}-dirty-{timestamp}

Requirements

• Python 3.11+
• Git repository
• LaTeX installation including:
  • XeLaTeX
  • BibTeX
  • latexdiff

Example

# In a Git repository containing LaTeX project
cd my-latex-project

# Install package
uv pip install -e /path/to/latex-builder

# Build current version and generate diffs
uv run latex-builder -v

This will:

1. Analyze current Git state
2. Generate version information files
3. Compile current version PDF
4. Generate diff documents with previous commit and previous tag
5. Output all files to output/ directory

Architecture

The package uses a modular architecture with clear separation of concerns:

• CLI Layer: Handles command line interaction
• Core Logic: Git operations, LaTeX processing, diff generation
• Configuration: Centralized settings management
• Utilities: Shared functionality for logging and command execution

Each module can be tested independently, following Python best practices.