trello-gantt 0.1.4

Generate Mermaid Gantt charts from Trello boards as standalone HTML files.

Gantt Chart Generation from Trello (POC)

Quick Start

pip install trello-gantt
cp .env.example .env        # fill in your Trello API key, token, and board ID
trello-gantt                 # generates output/gantt.html

To publish directly to Google Apps Script (optional):

python3 scripts/publish_gantt.py

See Automated publishing for first-time Google setup.

Overview

This project is a proof of concept that:

1. fetches tasks from Trello,
2. maps card data to a Gantt model,
3. generates Mermaid Gantt syntax,
4. renders a standalone HTML file with the chart and validation report.

The goal is to validate Trello as the source of truth for project timelines without using a heavy PM tool.

Prerequisites

• Python 3.10+ (tested with python3)
• Trello API credentials:
  • TRELLO_API_KEY
  • TRELLO_API_TOKEN

Setup

1. Create and activate a virtual environment:

python3 -m venv .venv
source .venv/bin/activate

2. Install dependencies:

pip install requests python-dotenv

3. Copy the example environment file and fill in your values:

cp .env.example .env

Edit .env with your Trello credentials and board configuration:

# Trello API credentials
TRELLO_API_KEY=your_api_key_here
TRELLO_API_TOKEN=your_api_token_here

# Accepts a full URL (https://trello.com/b/abc123/board-name) or just the ID
GANTT_BOARD_ID=https://trello.com/b/your_board_id/board-name

# Comma-separated list names to include. Leave empty to use all open lists.
GANTT_LISTS=To Do,In Progress,Done

GANTT_OUTPUT=output/gantt.html
GANTT_TITLE=Project Gantt Chart
# Comma-separated list names to render as milestones. Leave empty for none.
GANTT_MILESTONE_LISTS=Milestone 1,Milestone 2,Milestone 3

Usage

With .env configured, just run:

python3 -m src.main

All settings are read from .env. No arguments needed.

CLI arguments can override .env values when needed:

• --board-id: Trello board URL or ID. Env: GANTT_BOARD_ID
• --lists: comma-separated list names. Env: GANTT_LISTS
• --output (default gantt.html): output HTML file. Env: GANTT_OUTPUT
• --title (default Project Gantt Chart): diagram title. Env: GANTT_TITLE
• --milestone-list: comma-separated list names for milestones. Env: GANTT_MILESTONE_LISTS

Example with CLI overrides:

python3 -m src.main \
  --board-id "https://trello.com/b/7nlpWm2R/testing-gantt-chart" \
  --lists "TO DO,DOING,DONE 🎉" \
  --output output/gantt-selected.html \
  --title "Roadmap Sprint"

Interactive Features

The generated HTML includes interactive features that work directly in the browser:

• Filter by assignee: A dropdown at the top of the Gantt chart lets you filter tasks by team member. The chart re-renders in place while keeping the same time scale for easy comparison.
• Horizontal scroll: When the date range is large, the chart renders at full width with day-level tick marks inside a scrollable container.

Sharing the Gantt with Clients

The output is a standalone HTML file. To share it with non-technical users, you can publish it as a Google Apps Script Web App:

1. Create a project at https://script.google.com
2. Add a doGet() function that serves the HTML
3. Deploy as a web app with public access
4. Share the URL with clients — they open it in any browser, no setup needed

Automated publishing

A single command regenerates the Gantt and publishes it to the live web app:

python3 scripts/publish_gantt.py

This script:

1. Installs/verifies trello-gantt from PyPI
2. Generates the HTML from the Trello board
3. Uploads the HTML + access-controlled Code.gs to Google Apps Script via API
4. Creates a new version and updates the existing deployment (URL stays the same)

First-time setup:

1. Create a Google Cloud project and enable the Google Apps Script API
2. Create OAuth 2.0 Desktop credentials, download the JSON
3. Save it as credentials/google_oauth_client.json
4. Enable the Apps Script API in your user settings: https://script.google.com/home/usersettings
5. Run the script — it opens the browser once for authorization, then saves the token for future runs

Access control (allowlist by Google account) is built into the published Code.gs.

Field Mapping

Trello Field	Gantt Field	Notes
id / shortLink	task_id	Sanitized Mermaid-safe identifier
name	name	Sanitized and truncated for Mermaid parser safety
idList + board list map	section	Grouped by milestone label when present, else list name
due	end_date	If missing: processing_date + 1 day, used_due_fallback=True
start / due-1d	start_date	Explicit start wins, else end_date - 1 day
List column + dueComplete	status	Column → Mermaid modifier(s) for bar color; done if dueComplete
desc (## Progress section)	progress	Parsed from card description; 0-100, clamped. No section = 0%

Column → bar style (HTML/CSS): Backlog (gray), To Do (crit, white), Doing (active, blue), Done (done, green), Blocked (active,crit, orange). Add a Blocked list in Trello and include it in --lists when generating.

Progress Tracking

Since Trello's Free plan does not support Custom Fields, progress is tracked via a convention in the card description:

## Progress
72%

Parsing rules:

• No ## Progress section → 0%
• Valid number with or without % → that value (72% or 72 both work)
• Value above 100 → clamped to 100%
• Non-numeric value (hello, asdf70%, empty) → 0%

The percentage is displayed on each Gantt bar next to the task name (e.g. List filtering logic [YN] (72%)).

Start Date Heuristic

Current mapper uses this priority:

1. card.start if present (from Trello custom field / API)
2. otherwise end_date - 1 day (so the bar spans at least one day when due is set)

If due is missing, end_date is set to processing_date + 1 day and the same rule yields start_date == processing_date.

Validation Rules

Errors:

• no valid tasks after mapping
• end_date < start_date
• duplicate task_id

Warnings:

• list names requested by user not found
• cards without due (still included; informational)
• cards without assignee
• task names truncated
• more than 50% of cards missing due

Architecture

See docs/architecture.md for the full solution design, including module responsibilities, data flow, data structures, and technical decisions.

Tests

From the project root:

PYTHONPATH=. python3 -m unittest discover -s tests -v

Modules covered: field_mapper, mermaid_generator, validator (see tests/test_*.py).

Limitations (POC)

• No automatic dependency inference from Trello.
• High warning volume on boards where many cards lack due date.
• Limited CLI output format (console only, no JSON mode yet).

Feasibility Notes

The POC is technically viable:

• Trello data can be pulled reliably via API.
• Mermaid output renders correctly in standalone HTML.
• End-to-end execution with real board data is validated (see .claude/tasks/poc-for-gantt-chart-generation-from-trel/e2e-test-report.md).

To move from POC to an internal tool:

1. Expand automated tests (validator, trello_data, integration smoke with mocked API).
2. Add robust report artifacts (JSON summary + warning categories).
3. Improve list matching UX (fuzzy matching / suggestion for emoji list names).
4. Add optional overdue highlighting (crit) and richer status mapping.
5. Provide packaging and onboarding script for new developers.