Trouble CLI Tool Trouble in action - generating documentation from templates and data

You know that moment when you realize you’ve been manually updating the same doc umentation files across multiple projects, and you think “there has to be a better way”? T hat’s exactly where I found myself a few months ago, drowning in repetitive documenta tion tasks and looking for a solution.

That frustration led me to build Trouble - a CLI tool that started as a simp le script to generate documentation from templates but evolved into something much more interesting: a flexible system for automated documentation generation that actually works.

🛠️ What is Trouble?

Trouble is a Python-based CLI tool designed to generate static documentation files (Markdown or HTML) that can be published via GitHub Pages. It’s particularly useful for projects that need automated documentation generation as

part of their CI/CD pipeline.

🎯 Key Features

Template-Based Generation

Trouble uses Python’s string.Template for flexible templating, allowing you to

create reusable templates for different types of documentation:

  • Markdown templates (.md.template)
  • HTML templates (.html.template)
  • Variable substitution using ${variable} syntax

JSON-Driven Content

The tool reads page data from a trouble/data.json file, where each key represents a page with associated metadata:

{
  "page_one": {
    "title": "Hello World",
    "content": "This is the first page generated by Trouble.",
    "filename": "page_one.html"
  }
}

GitHub Actions Integration

Trouble is designed to work seamlessly with GitHub Actions, automatically generating and publishing documentation when changes are merged to the main branch.

🚀 How It Works

Basic Usage

# Generate documentation from templates
python -m trouble generate

The generate command:

  1. Reads page data from trouble/data.json
  2. Processes templates in the trouble/templates/ directory
  3. Outputs generated files to the docs/ directory
  4. Supports both Markdown and HTML output formats

Template System

Templates use Python’s string.Template syntax for variable substitution:

<!DOCTYPE html>
<html>
<head>
    <title>${title}</title>
</head>
<body>
    <h1>${title}</h1>
    <p>${content}</p>
</body>
</html>

GitHub Actions Workflow

The project includes a .github/workflows/publish.yml file that defines the GitHub Action for automated documentation publishing:

name: Publish Documentation
on:
  push:
    branches: [main]
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Generate Documentation
        run: python -m trouble generate
      - name: Deploy to GitHub Pages
        # ... deployment steps

🎨 Use Cases

Trouble is perfect for:

  • Project documentation that needs to be generated from data
  • API documentation with dynamic content
  • Report generation from structured data
  • Static site generation for simple projects
  • Automated documentation in CI/CD pipelines

🔧 The Development Journey

Development Process The evolution from simple script to comprehensive CLI tool

Looking at the commit history, I can see exactly where Trouble evolved from a si mple script into something more sophisticated. The early commits show basic function ality, but then something interesting happened - I started collaborating with AI agent s to improve the tool.

The AI Collaboration

One of the most fascinating aspects of developing Trouble was the AI collaborati on. Looking at commits like 88406a93 (“Refactor: Improve etude discovery and logg ing”), I can see where AI agents (specifically Cursor Agent) helped improve the codeba se.

The AI didn’t just write code - it helped me think through problems differently. When I was stuck on the etude discovery system, the AI suggested a completely d ifferent approach that was more robust and maintainable.

The Data Build Failures

One of the most challenging periods was dealing with data build failures. Lookin g at commit 3866631a (“Investigate data build failures and alternative api”), I can see exactly where this became a major focus.

The issue was that the tool was trying to fetch data from external APIs that wer en’t always reliable. The solution was to implement a more robust data fetching syst em with proper error handling and fallback mechanisms.

The Testing Evolution

Testing a CLI tool that generates documentation is… interesting. How do you te st something that’s designed to produce different output every time? The solution was to focus on testing the process, not the output - ensuring that the tool coul d handle various input formats, error conditions, and edge cases without crashing .

📊 Project Structure

trouble/
├── trouble/              # Main Python package
│   ├── __init__.py
│   ├── generate.py       # Core generation logic
│   └── templates/        # Template files
├── data.json            # Page data configuration
├── docs/                # Generated output
└── .github/workflows/   # CI/CD configuration

🚀 Getting Started

To use Trouble in your own project:

  1. Install the tool:

    pip install trouble

  2. Create your data file:

    {
  "my_page": {
    "title": "My Page",
    "content": "This is my generated page.",
    "filename": "my_page.html"
  }
}

  3. Create templates:

    <!-- templates/page.html.template -->
<h1>${title}</h1>
<p>${content}</p>

  4. Generate documentation:

    python -m trouble generate

🔗 Links and Resources

🎯 Future Development

Planned enhancements include:

  • More template engines (Jinja2, Mustache)
  • Configuration file support (YAML, TOML)
  • Plugin system for custom generators
  • Watch mode for development
  • Advanced templating features

💡 What I Learned About Documentation and AI

Project Reflection The intersection of documentation, automation, and AI collaboration

Building Trouble taught me more about documentation than I expected. The biggest revelation? Good documentation isn’t just about writing - it’s about creating s ystems that keep documentation current and useful.

The Documentation Problem

The real problem with documentation isn’t that it’s hard to write - it’s that it ‘s hard to keep current. Code changes, APIs evolve, and documentation becomes outd ated faster than you can update it manually.

Trouble solves this by making documentation generation part of the development p rocess. When your code changes, your documentation updates automatically. It’s not perf ect, but it’s a lot better than manually maintaining dozens of documentation files.

The AI Collaboration Experience

Working with AI agents on this project was eye-opening. The AI didn’t just write code - it helped me think through problems differently. When I was stuck on a p articular issue, the AI would suggest approaches I hadn’t considered.

But it also taught me that AI collaboration isn’t about replacing human thinking

  • it’s about augmenting it. The AI could generate code quickly, but I still nee ded to understand the problem, evaluate the solutions, and make the final decisions .

The Name

I named it “Trouble” because that’s exactly what it solves - the trouble of main taining documentation manually. It’s not a fancy name, but it’s honest about what the t ool does.

If you’re tired of manually updating documentation or want to experiment with A I-assisted development, check out Trouble. It might ju st change how you think about documentation and automation!