pkl-docgen

🚧 This is a work in progress. Expect frequent breaking changes.

A modern documentation generator for Pkl modules using Go and Templ, because Java is indeed hot ass.

Why This Project Exists

The official Pkl documentation generator (Pkldoc) is implemented in Java, which has several drawbacks:

1. It's Java: Need we say more? Fine, we will...
2. Slow AF Startup: Nothing says "productivity" like waiting for the JVM to warm up while you contemplate your life choices.
3. Memory Hunger: Java tools devour RAM like it's an all-you-can-eat buffet.
4. JVM Dependency: "Let me just install and configure this entire virtual machine to generate some docs real quick" — said no one ever.
5. Complex Codebase: Because apparently simple, readable code wasn't on the requirements list.

pkl-docgen addresses these issues by providing a Go-based alternative that:

• Is Blazingly Fast: Go compiles to native code, so you can generate docs before your coffee gets cold.
• Has No JVM Dependency: Run a single binary without explaining to your computer what a classpath is.
• Is Simpler to Extend: Uses straightforward Go code that won't make you question your career choices.
• Has a Smaller Footprint: Produces binaries that don't require their own zip code.
• Uses Modern Web Templates: Leverages Templ for type-safe HTML templates that don't shit the bed when you use a conditional.

Features

• Parse and document Pkl modules, classes, properties, functions, and type aliases
• Generate clean, searchable HTML documentation
• Support for Markdown in documentation comments
• Member navigation and search
• Cross-references between modules
• Won't make your computer fans sound like a jet engine

Installation

From Source

# Clone the repository
git clone https://github.com/prnk28/pkl-docgen.git
cd pkl-docgen

# Install dependencies
make deps

# Build the binary
make build

# Optionally install the binary
make install

Using Go Install

go install github.com/prnk28/pkl-docgen/cmd/pkl-docgen@latest

Usage

# Basic usage
pkl-docgen -output-dir=./docs -static-dir=./web path/to/your/pkl/module.pkl

# Multiple modules
pkl-docgen -output-dir=./docs -static-dir=./web module1.pkl module2.pkl

# Help
pkl-docgen -help

Options

• -output-dir: Directory where documentation will be generated (default: "pkldoc")
• -static-dir: Directory containing static assets (CSS, JS, images)
• -help: Show help information for when you inevitably forget the above options

Development

# Generate templ code after changes
make generate

# Build the binary
make build

# Run with a sample module
make run MODULE_PATH=./examples/config.pkl

# Run tests
make test

How It Works

pkl-docgen uses the official Pkl Go bindings to parse and evaluate Pkl modules, because reinventing the wheel is overrated. It extracts documentation metadata from the modules and generates HTML documentation using the Templ framework.

1. Parsing: Uses the Pkl evaluator to extract module structure and documentation
2. Processing: Converts Pkl types and structures to Go data models without unnecessary complexity
3. Rendering: Uses Templ templates that don't collapse when you use a conditional statement
4. Static Assets: Includes CSS and JavaScript for search and navigation that won't take 5 seconds to load

Architecture

We've broken down the components into small, focused pieces that do one thing well - a revolutionary concept apparently:

• Parser: Extracts documentation from Pkl modules without making your CPU cry
• Templates: Modular Templ components that render the documentation without mysterious failures
• CLI: A simple command-line interface that doesn't require a PhD to operate

License

MIT License

Acknowledgements

• Pkl Language - The configuration language by Apple
• Templ - The templating library for Go that respects your sanity

Built because life's too short for slow documentation generators.