Project Management

class ProjectsExtension(Extension):
    """
    Markdown extension for project management features.
    
    Configuration:
    - priority: Extension processing priority (default: 12)
    """
    config = {"priority": [12, "The priority to be configured for the extension."]}
    
    def extendMarkdown(self, md):
        """
        Registers Gantt processors with the Markdown parser.
        
        Parameters:
        - md: Markdown parser instance
        """

class GanttEmbeddedProcessor(BaseGanttProcessor, EmbeddedBlockProcessor):
    """
    Block processor for embedded Gantt data using ::gantt:: syntax.
    """

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

class BaseGanttProcessor:
    """
    Base class for Gantt processors with common functionality.
    """
    @property
    def name(self) -> str:
        """Returns 'gantt' as the processor name."""
    
    def build_html(self, parent, obj, props) -> None:
        """
        Builds HTML for Gantt chart components.
        
        Parameters:
        - parent: Parent XML element
        - obj: Plan data (dict or list)
        - props: Configuration properties
        """

def register_extension(md, priority):
    """
    Registers Gantt processors with the Markdown parser.
    
    Parameters:
    - md: Markdown parser instance
    - priority: Processing priority
    """

class Event:
    """
    Represents a project event or milestone.
    
    Attributes:
    - title: Event title
    - description: Optional event description
    - time: Event timestamp
    - icon: Optional icon identifier
    """
    title: str
    description: Optional[str]
    time: Optional[datetime]
    icon: Optional[str]
    
    @classmethod
    def from_obj(cls, obj):
        """
        Creates Event from dictionary data.
        
        Parameters:
        - obj: Dictionary with event data
        
        Returns:
        Event: Event instance
        """

class Activity:
    """
    Represents a project activity with optional sub-activities and events.
    
    Attributes:
    - title: Activity title
    - start: Activity start date
    - end: Activity end date
    - description: Optional activity description
    - activities: List of sub-activities
    - events: List of associated events
    - hidden: Whether activity is hidden from display
    """
    title: str
    start: Optional[date]
    end: Optional[date]
    description: Optional[str]
    activities: Optional[List[Activity]]
    events: Optional[List[Event]]
    hidden: Optional[bool]
    
    def iter_activities(self, include_self=True):
        """
        Iterates through all activities including sub-activities.
        
        Parameters:
        - include_self: Whether to include this activity
        
        Yields:
        Activity: Activity instances
        """
    
    def iter_events(self, include_self=True):
        """
        Iterates through all events including sub-activity events.
        
        Parameters:
        - include_self: Whether to include this activity's events
        
        Yields:
        Event: Event instances
        """
    
    def get_overall_start(self) -> Optional[date]:
        """
        Gets the earliest start date including sub-activities.
        
        Returns:
        Optional[date]: Earliest start date or None
        """
    
    def get_overall_end(self) -> Optional[date]:
        """
        Gets the latest end date including sub-activities.
        
        Returns:
        Optional[date]: Latest end date or None
        """
    
    @classmethod
    def from_obj(cls, obj, preceding_date=None):
        """
        Creates Activity from dictionary data.
        
        Parameters:
        - obj: Dictionary with activity data
        - preceding_date: Previous activity's end date
        
        Returns:
        Activity: Activity instance
        """

class Plan(Activity):
    """
    Represents a complete project plan.
    """
    @classmethod
    def from_obj(cls, obj):
        """
        Creates Plan from list or dictionary data.
        
        Parameters:
        - obj: Plan data structure
        
        Returns:
        Plan: Plan instance
        """

class GanttViewOptions:
    """
    Configuration options for Gantt chart rendering.
    
    Attributes:
    - id: HTML ID attribute
    - month_width: Width per month in pixels
    - month_format: Month display format string
    - whole_years: Whether to show complete years only
    - no_groups: Whether to hide activity grouping
    - no_years: Whether to hide year labels
    - no_weeks: Whether to hide week labels  
    - no_quarters: Whether to hide quarter labels
    - no_days: Whether to hide day labels
    - pastello: Whether to use pastel color scheme
    - vlines_pace: Vertical grid lines spacing
    """
    id: Optional[str]
    month_width: float
    month_format: str
    whole_years: bool
    no_groups: bool
    no_years: bool
    no_weeks: bool
    no_quarters: bool
    no_days: bool
    pastello: bool
    vlines_pace: VerticalLinesPace

class GanttHTMLBuilder:
    """
    Builds HTML for Gantt chart components.
    """
    def build_html(self, parent) -> None:
        """
        Builds complete Gantt chart HTML structure.
        
        Parameters:
        - parent: Parent XML element
        """
    
    def build_event(self, parent, event: Event) -> None:
        """
        Builds HTML for project event markers.
        
        Parameters:
        - parent: Parent XML element
        - event: Event to render
        """

class Quarter:
    """
    Represents a calendar quarter with year and quarter number.
    """

class InvalidLastsValue(Exception):
    """
    Raised when duration value cannot be parsed.
    """

class UnsupportedLastsUnit(Exception):
    """
    Raised when duration unit is not supported.
    """

def parse_lasts(value: str):
    """
    Parses duration strings like "30 days", "3 months".
    
    Parameters:
    - value: Duration string
    
    Returns:
    Parsed duration object
    
    Raises:
    InvalidLastsValue: If value format is invalid
    UnsupportedLastsUnit: If unit is not supported
    """

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

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

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

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

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

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

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

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

::gantt::
title: "Website Redesign Project"
activities:
  - title: "Planning Phase"
    start: "2024-01-01"
    end: "2024-01-31"
    
  - title: "Design Phase"
    start: "2024-02-01"
    end: "2024-03-15"
    
  - title: "Development"
    start: "2024-03-01"
    end: "2024-05-31"
    
  - title: "Testing & Launch"
    start: "2024-06-01"
    end: "2024-06-30"
::end-gantt::

::gantt::
title: "Software Development Project"
activities:
  - title: "Backend Development"
    start: "2024-01-01"
    end: "2024-04-30"
    activities:
      - title: "Database Design"
        start: "2024-01-01"
        end: "2024-01-15"
      - title: "API Development"
        start: "2024-01-16"
        end: "2024-03-31"
      - title: "Testing"
        start: "2024-04-01"
        end: "2024-04-30"
        
  - title: "Frontend Development"
    start: "2024-02-01"
    end: "2024-05-15"
    activities:
      - title: "UI Design"
        start: "2024-02-01"
        end: "2024-02-28"
      - title: "Component Development"
        start: "2024-03-01"
        end: "2024-04-30"
      - title: "Integration"
        start: "2024-05-01"
        end: "2024-05-15"
::end-gantt::

::gantt::
title: "Project Timeline with Milestones"
activities:
  - title: "Research & Planning"
    start: "2024-01-01"
    end: "2024-02-15"
    events:
      - title: "Requirements Review"
        time: "2024-01-15"
        icon: "check-circle"
      - title: "Architecture Approval"
        time: "2024-02-10"
        icon: "thumbs-up"
        
  - title: "Implementation"
    start: "2024-02-16"
    end: "2024-05-31"
    events:
      - title: "Alpha Release"
        time: "2024-04-01"
        icon: "tag"
      - title: "Beta Release"
        time: "2024-05-01"
        icon: "tag"
        
  - title: "Deployment"
    start: "2024-06-01" 
    end: "2024-06-15"
    events:
      - title: "Go Live"
        time: "2024-06-15"  
        icon: "rocket"
::end-gantt::

::gantt:: id="project-gantt" month_width=80 pastello=true no_weeks=true
title: "Marketing Campaign"
activities:
  - title: "Campaign Planning"
    start: "2024-Q1"
    end: "2024-Q1"
    
  - title: "Content Creation"
    start: "2024-Q2"
    end: "2024-Q3"
    
  - title: "Campaign Launch"
    start: "2024-Q4"
    end: "2024-Q4"
::end-gantt::

[gantt(project-timeline.yaml)]

title: "Product Development"
activities:
  - title: "Phase 1"
    start: "2024-01-01"
    end: "2024-03-31"
  - title: "Phase 2" 
    start: "2024-04-01"
    end: "2024-06-30"

# ISO date format
start: "2024-01-15"

# Quarter notation
start: "2024-Q1"
end: "2024-Q2"

# Month notation
start: "2024-01"
end: "2024-03"

# Relative dates
start: "today"
end: "30 days"

activities:
  - title: "Task 1"
    start: "2024-01-01"
    duration: "2 weeks"
    
  - title: "Task 2"
    start: "2024-01-15"
    duration: "1 month"

<div class="gantt-chart" id="project-gantt">
  <div class="gantt-header">
    <div class="gantt-timeline">...</div>
  </div>
  <div class="gantt-body">
    <div class="gantt-activity">...</div>
    <div class="gantt-event">...</div>
  </div>
</div>