trello-gantt 0.1.3

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

Gantt Chart Generation from Trello (POC)

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

To update: regenerate the HTML with python3 -m src.main, paste the content into the Apps Script editor, and redeploy. The URL stays the same.

Optional access control (allowlist by Google account) is also supported.

For detailed step-by-step instructions, see docs/sharing-via-google-apps-script.md.

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.