Metadata-Version: 2.4
Name: trello-gantt
Version: 0.1.5
Summary: Generate Mermaid Gantt charts from Trello boards as standalone HTML files.
Author: DSpot Automation
License-Expression: MIT
Project-URL: Homepage, https://github.com/DSpot-Automation/gantt-chart-generation
Project-URL: Repository, https://github.com/DSpot-Automation/gantt-chart-generation
Keywords: trello,gantt,mermaid,project-management,chart
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Scheduling
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Requires-Dist: python-dotenv>=1.0
Dynamic: license-file

# Gantt Chart Generation from Trello (POC)

## Quick Start

```bash
pip install trello-gantt
trello-gantt init            # creates a .env file — fill in your credentials
trello-gantt                 # generates the Gantt HTML
```

To publish directly to Google Apps Script (optional):

```bash
python3 scripts/publish_gantt.py
```

See [Automated publishing](#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:

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

2. Install dependencies:

```bash
pip install requests python-dotenv
```

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

```bash
cp .env.example .env
```

Edit `.env` with your Trello credentials and board configuration:

```env
# 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:

```bash
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:

```bash
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:

```bash
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:

```markdown
## 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](docs/architecture.md) for the full solution design, including module responsibilities, data flow, data structures, and technical decisions.

## Tests

From the project root:

```bash
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).
4. Improve list matching UX (fuzzy matching / suggestion for emoji list names).
5. Add optional overdue highlighting (`crit`) and richer status mapping.
6. Provide packaging and onboarding script for new developers.
