0
# Project Management
1

2
Gantt chart visualization for project planning and timeline management. This Markdown extension provides comprehensive project management capabilities including activities, sub-activities, events, and flexible time scales for creating professional Gantt charts and project timelines.
3

4
## Capabilities
5

6
### Extension Configuration
7

8
Configure the projects extension which includes Gantt chart functionality.
9

10
```python { .api }
11
class ProjectsExtension(Extension):
12
    """
13
    Markdown extension for project management features.
14
    
15
    Configuration:
16
    - priority: Extension processing priority (default: 12)
17
    """
18
    config = {"priority": [12, "The priority to be configured for the extension."]}
19
    
20
    def extendMarkdown(self, md):
21
        """
22
        Registers Gantt processors with the Markdown parser.
23
        
24
        Parameters:
25
        - md: Markdown parser instance
26
        """
27
```
28

29
### Gantt Processing
30

31
The extension supports two processing modes for Gantt chart data.
32

33
```python { .api }
34
class GanttEmbeddedProcessor(BaseGanttProcessor, EmbeddedBlockProcessor):
35
    """
36
    Block processor for embedded Gantt data using ::gantt:: syntax.
37
    """
38

39
class GanttSourceProcessor(BaseGanttProcessor, SourceBlockProcessor):
40
    """
41
    Block processor for external Gantt data using [gantt(...)] syntax.
42
    """
43

44
class BaseGanttProcessor:
45
    """
46
    Base class for Gantt processors with common functionality.
47
    """
48
    @property
49
    def name(self) -> str:
50
        """Returns 'gantt' as the processor name."""
51
    
52
    def build_html(self, parent, obj, props) -> None:
53
        """
54
        Builds HTML for Gantt chart components.
55
        
56
        Parameters:
57
        - parent: Parent XML element
58
        - obj: Plan data (dict or list)
59
        - props: Configuration properties
60
        """
61

62
def register_extension(md, priority):
63
    """
64
    Registers Gantt processors with the Markdown parser.
65
    
66
    Parameters:
67
    - md: Markdown parser instance
68
    - priority: Processing priority
69
    """
70
```
71

72
## Data Models
73

74
### Project Data Structures
75

76
```python { .api }
77
class Event:
78
    """
79
    Represents a project event or milestone.
80
    
81
    Attributes:
82
    - title: Event title
83
    - description: Optional event description
84
    - time: Event timestamp
85
    - icon: Optional icon identifier
86
    """
87
    title: str
88
    description: Optional[str]
89
    time: Optional[datetime]
90
    icon: Optional[str]
91
    
92
    @classmethod
93
    def from_obj(cls, obj):
94
        """
95
        Creates Event from dictionary data.
96
        
97
        Parameters:
98
        - obj: Dictionary with event data
99
        
100
        Returns:
101
        Event: Event instance
102
        """
103

104
class Activity:
105
    """
106
    Represents a project activity with optional sub-activities and events.
107
    
108
    Attributes:
109
    - title: Activity title
110
    - start: Activity start date
111
    - end: Activity end date
112
    - description: Optional activity description
113
    - activities: List of sub-activities
114
    - events: List of associated events
115
    - hidden: Whether activity is hidden from display
116
    """
117
    title: str
118
    start: Optional[date]
119
    end: Optional[date]
120
    description: Optional[str]
121
    activities: Optional[List[Activity]]
122
    events: Optional[List[Event]]
123
    hidden: Optional[bool]
124
    
125
    def iter_activities(self, include_self=True):
126
        """
127
        Iterates through all activities including sub-activities.
128
        
129
        Parameters:
130
        - include_self: Whether to include this activity
131
        
132
        Yields:
133
        Activity: Activity instances
134
        """
135
    
136
    def iter_events(self, include_self=True):
137
        """
138
        Iterates through all events including sub-activity events.
139
        
140
        Parameters:
141
        - include_self: Whether to include this activity's events
142
        
143
        Yields:
144
        Event: Event instances
145
        """
146
    
147
    def get_overall_start(self) -> Optional[date]:
148
        """
149
        Gets the earliest start date including sub-activities.
150
        
151
        Returns:
152
        Optional[date]: Earliest start date or None
153
        """
154
    
155
    def get_overall_end(self) -> Optional[date]:
156
        """
157
        Gets the latest end date including sub-activities.
158
        
159
        Returns:
160
        Optional[date]: Latest end date or None
161
        """
162
    
163
    @classmethod
164
    def from_obj(cls, obj, preceding_date=None):
165
        """
166
        Creates Activity from dictionary data.
167
        
168
        Parameters:
169
        - obj: Dictionary with activity data
170
        - preceding_date: Previous activity's end date
171
        
172
        Returns:
173
        Activity: Activity instance
174
        """
175

176
class Plan(Activity):
177
    """
178
    Represents a complete project plan.
179
    """
180
    @classmethod
181
    def from_obj(cls, obj):
182
        """
183
        Creates Plan from list or dictionary data.
184
        
185
        Parameters:
186
        - obj: Plan data structure
187
        
188
        Returns:
189
        Plan: Plan instance
190
        """
191
```
192

193
### HTML Rendering
194

195
```python { .api }
196
class GanttViewOptions:
197
    """
198
    Configuration options for Gantt chart rendering.
199
    
200
    Attributes:
201
    - id: HTML ID attribute
202
    - month_width: Width per month in pixels
203
    - month_format: Month display format string
204
    - whole_years: Whether to show complete years only
205
    - no_groups: Whether to hide activity grouping
206
    - no_years: Whether to hide year labels
207
    - no_weeks: Whether to hide week labels  
208
    - no_quarters: Whether to hide quarter labels
209
    - no_days: Whether to hide day labels
210
    - pastello: Whether to use pastel color scheme
211
    - vlines_pace: Vertical grid lines spacing
212
    """
213
    id: Optional[str]
214
    month_width: float
215
    month_format: str
216
    whole_years: bool
217
    no_groups: bool
218
    no_years: bool
219
    no_weeks: bool
220
    no_quarters: bool
221
    no_days: bool
222
    pastello: bool
223
    vlines_pace: VerticalLinesPace
224

225
class GanttHTMLBuilder:
226
    """
227
    Builds HTML for Gantt chart components.
228
    """
229
    def build_html(self, parent) -> None:
230
        """
231
        Builds complete Gantt chart HTML structure.
232
        
233
        Parameters:
234
        - parent: Parent XML element
235
        """
236
    
237
    def build_event(self, parent, event: Event) -> None:
238
        """
239
        Builds HTML for project event markers.
240
        
241
        Parameters:
242
        - parent: Parent XML element
243
        - event: Event to render
244
        """
245
```
246

247
### Time Utilities
248

249
```python { .api }
250
class Quarter:
251
    """
252
    Represents a calendar quarter with year and quarter number.
253
    """
254

255
class InvalidLastsValue(Exception):
256
    """
257
    Raised when duration value cannot be parsed.
258
    """
259

260
class UnsupportedLastsUnit(Exception):
261
    """
262
    Raised when duration unit is not supported.
263
    """
264

265
def parse_lasts(value: str):
266
    """
267
    Parses duration strings like "30 days", "3 months".
268
    
269
    Parameters:
270
    - value: Duration string
271
    
272
    Returns:
273
    Parsed duration object
274
    
275
    Raises:
276
    InvalidLastsValue: If value format is invalid
277
    UnsupportedLastsUnit: If unit is not supported
278
    """
279

280
def iter_years_between_dates(start: date, end: date):
281
    """Iterates years in date range."""
282

283
def iter_months_between_dates(start: date, end: date):
284
    """Iterates months in date range."""
285

286
def iter_weeks_between_dates(start: date, end: date):
287
    """Iterates weeks in date range."""
288

289
def iter_days_between_dates(start: date, end: date):
290
    """Iterates days in date range."""
291

292
def iter_quarters_between_dates(start: date, end: date):
293
    """Iterates quarters in date range."""
294

295
def get_first_day_of_month(year: int, month: int) -> date:
296
    """Gets first day of specified month."""
297

298
def get_last_day_of_month(year: int, month: int) -> date:
299
    """Gets last day of specified month."""
300

301
def date_delta(start: date, end: date) -> int:
302
    """Calculates difference between dates in days."""
303
```
304

305
## Usage Examples
306

307
### Basic Gantt Chart
308

309
Use `::gantt::` blocks with project data:
310

311
```markdown
312
::gantt::
313
title: "Website Redesign Project"
314
activities:
315
  - title: "Planning Phase"
316
    start: "2024-01-01"
317
    end: "2024-01-31"
318
    
319
  - title: "Design Phase"
320
    start: "2024-02-01"
321
    end: "2024-03-15"
322
    
323
  - title: "Development"
324
    start: "2024-03-01"
325
    end: "2024-05-31"
326
    
327
  - title: "Testing & Launch"
328
    start: "2024-06-01"
329
    end: "2024-06-30"
330
::end-gantt::
331
```
332

333
### Gantt with Sub-Activities
334

335
```markdown
336
::gantt::
337
title: "Software Development Project"
338
activities:
339
  - title: "Backend Development"
340
    start: "2024-01-01"
341
    end: "2024-04-30"
342
    activities:
343
      - title: "Database Design"
344
        start: "2024-01-01"
345
        end: "2024-01-15"
346
      - title: "API Development"
347
        start: "2024-01-16"
348
        end: "2024-03-31"
349
      - title: "Testing"
350
        start: "2024-04-01"
351
        end: "2024-04-30"
352
        
353
  - title: "Frontend Development"
354
    start: "2024-02-01"
355
    end: "2024-05-15"
356
    activities:
357
      - title: "UI Design"
358
        start: "2024-02-01"
359
        end: "2024-02-28"
360
      - title: "Component Development"
361
        start: "2024-03-01"
362
        end: "2024-04-30"
363
      - title: "Integration"
364
        start: "2024-05-01"
365
        end: "2024-05-15"
366
::end-gantt::
367
```
368

369
### Gantt with Events and Milestones
370

371
```markdown
372
::gantt::
373
title: "Project Timeline with Milestones"
374
activities:
375
  - title: "Research & Planning"
376
    start: "2024-01-01"
377
    end: "2024-02-15"
378
    events:
379
      - title: "Requirements Review"
380
        time: "2024-01-15"
381
        icon: "check-circle"
382
      - title: "Architecture Approval"
383
        time: "2024-02-10"
384
        icon: "thumbs-up"
385
        
386
  - title: "Implementation"
387
    start: "2024-02-16"
388
    end: "2024-05-31"
389
    events:
390
      - title: "Alpha Release"
391
        time: "2024-04-01"
392
        icon: "tag"
393
      - title: "Beta Release"
394
        time: "2024-05-01"
395
        icon: "tag"
396
        
397
  - title: "Deployment"
398
    start: "2024-06-01" 
399
    end: "2024-06-15"
400
    events:
401
      - title: "Go Live"
402
        time: "2024-06-15"  
403
        icon: "rocket"
404
::end-gantt::
405
```
406

407
### Custom Gantt Styling
408

409
```markdown
410
::gantt:: id="project-gantt" month_width=80 pastello=true no_weeks=true
411
title: "Marketing Campaign"
412
activities:
413
  - title: "Campaign Planning"
414
    start: "2024-Q1"
415
    end: "2024-Q1"
416
    
417
  - title: "Content Creation"
418
    start: "2024-Q2"
419
    end: "2024-Q3"
420
    
421
  - title: "Campaign Launch"
422
    start: "2024-Q4"
423
    end: "2024-Q4"
424
::end-gantt::
425
```
426

427
### External Gantt Data
428

429
Reference external project data:
430

431
```markdown
432
[gantt(project-timeline.yaml)]
433
```
434

435
Where `project-timeline.yaml` contains:
436
```yaml
437
title: "Product Development"
438
activities:
439
  - title: "Phase 1"
440
    start: "2024-01-01"
441
    end: "2024-03-31"
442
  - title: "Phase 2" 
443
    start: "2024-04-01"
444
    end: "2024-06-30"
445
```
446

447
## Data Source Support
448

449
### Supported Formats
450

451
- **YAML**: Structured project data (recommended)
452
- **JSON**: JavaScript Object Notation format
453
- **CSV**: Comma-separated values for simple activities
454

455
### Date Formats
456

457
The extension supports various date formats:
458

459
```yaml
460
# ISO date format
461
start: "2024-01-15"
462

463
# Quarter notation
464
start: "2024-Q1"
465
end: "2024-Q2"
466

467
# Month notation
468
start: "2024-01"
469
end: "2024-03"
470

471
# Relative dates
472
start: "today"
473
end: "30 days"
474
```
475

476
### Duration Specifications
477

478
Activities can specify duration instead of end dates:
479

480
```yaml
481
activities:
482
  - title: "Task 1"
483
    start: "2024-01-01"
484
    duration: "2 weeks"
485
    
486
  - title: "Task 2"
487
    start: "2024-01-15"
488
    duration: "1 month"
489
```
490

491
## Styling and Customization
492

493
### View Options
494

495
- `month_width`: Pixels per month (default: 60)
496
- `month_format`: Date format for month labels
497
- `whole_years`: Show complete years only
498
- `no_groups`: Hide activity grouping
499
- `no_years/no_quarters/no_weeks/no_days`: Hide time scale elements
500
- `pastello`: Use pastel color scheme
501

502
### CSS Classes
503

504
Generated HTML includes semantic CSS classes:
505

506
```html
507
<div class="gantt-chart" id="project-gantt">
508
  <div class="gantt-header">
509
    <div class="gantt-timeline">...</div>
510
  </div>
511
  <div class="gantt-body">
512
    <div class="gantt-activity">...</div>
513
    <div class="gantt-event">...</div>
514
  </div>
515
</div>
516
```
517

518
### Responsive Design
519

520
The Gantt charts support responsive design with horizontal scrolling for wide timelines and collapsible activity groups for better mobile experience.