needgantt

New in version 0.5.5.

needgantt adds a gantt-chart to your documentation.

Example

.. needgantt:: Bug handling gantt
   :tags: gantt_example
   :milestone_filter: type == 'milestone'

Result

@startuml

' Elements definition 

[Find & Report bug] as [ACT_BUG] lasts 5 days
[Analyse bug] as [ACT_BUG_ANALYSE] lasts 7 days
[Create solution ticket] as [ACT_TICKET] lasts 3 days
[Work on solution ticket] as [ACT_TICKET_WORK] lasts 7 days
[Solution ticket closed] as [MS_TICKET_CLOSED] lasts 0 days
[Add solution to release plan] as [ACT_RELEASE_PLAN] lasts 1 days
[Deploy release] as [ACT_DEPLOY] lasts 2 days
[Test release] as [ACT_TEST] lasts 12 days
[Bug solved] as [MS_BUG_SOLVED] lasts 0 days

' Element links definition 


' Deactivated, as currently supported by plantuml beta only
' Element completion definition 

[Test release] is 80% completed


' Element color definition 

[Find & Report bug] is colored in #FFCC00
[Analyse bug] is colored in #FFCC00
[Create solution ticket] is colored in #FFCC00
[Work on solution ticket] is colored in #FFCC00
[Solution ticket closed] is colored in #FF3333
[Add solution to release plan] is colored in #FFCC00
[Deploy release] is colored in #FFCC00
[Test release] is colored in #FFCC00
[Bug solved] is colored in #FF3333


' Constraints definition 


' Constraints definition 

[ACT_BUG_ANALYSE] starts at [ACT_BUG]'s end
[ACT_TICKET] starts at [ACT_BUG_ANALYSE]'s end
[ACT_TICKET_WORK] starts at [ACT_TICKET]'s end
[MS_TICKET_CLOSED] happens at [ACT_TICKET_WORK]'s end
[ACT_RELEASE_PLAN] starts at [MS_TICKET_CLOSED]'s end
[ACT_DEPLOY] starts at [ACT_RELEASE_PLAN]'s end
[ACT_TEST] starts at [ACT_DEPLOY]'s end
[MS_BUG_SOLVED] happens at [ACT_TEST]'s end

@enduml

Bug handling gantt

Show used needs for above example

Action: Find & Report bug ACT_BUG ../_images/arrow-right-circle.svg
tags: gantt_example
duration: 5
links incoming: ACT_BUG_ANALYSE
Action: Analyse bug ACT_BUG_ANALYSE ../_images/arrow-right-circle.svg
tags: gantt_example
duration: 7
links outgoing: ACT_BUG
links incoming: ACT_TICKET
Action: Create solution ticket ACT_TICKET ../_images/arrow-right-circle.svg
tags: gantt_example
duration: 3
links outgoing: ACT_BUG_ANALYSE
links incoming: ACT_TICKET_WORK
Action: Work on solution ticket ACT_TICKET_WORK ../_images/arrow-right-circle.svg
tags: gantt_example
duration: 7
links outgoing: ACT_TICKET
links incoming: MS_TICKET_CLOSED
Milestone: Solution ticket closed MS_TICKET_CLOSED ../_images/arrow-right-circle.svg
tags: gantt_example
links outgoing: ACT_TICKET_WORK
links incoming: ACT_RELEASE_PLAN
Action: Add solution to release plan ACT_RELEASE_PLAN ../_images/arrow-right-circle.svg
tags: gantt_example
duration: 1
links outgoing: MS_TICKET_CLOSED
links incoming: ACT_DEPLOY
Action: Deploy release ACT_DEPLOY ../_images/arrow-right-circle.svg
tags: gantt_example
duration: 2
links outgoing: ACT_RELEASE_PLAN
links incoming: ACT_TEST
Action: Test release ACT_TEST ../_images/arrow-right-circle.svg
tags: gantt_example
duration: 12
completion: 80%
links outgoing: ACT_DEPLOY
links incoming: MS_BUG_SOLVED
Milestone: Bug solved MS_BUG_SOLVED ../_images/arrow-right-circle.svg
tags: gantt_example
links outgoing: ACT_TEST

Hint

The Gantt function is quite new in PlantUML and some features are available in the Beta version only. So if you get any syntax errors during the build, please download the latest PlantUML version.

If svg is set as output format for PlantUML, we link the tasks elements to their related need.

We take the colors for the chart from the needs_types configuration. You can deactivate this behavior by setting no_color.

needgantt supports the following relationship between tasks and milestones:

By default, the need-option duration defines the task length. We interpret the value in days.

By default, the need-option completion defines the task completion. We interpret the value as percentage and should be between 0 and 100.

Options

milestone_filter

We execute the milestone_filter on each need found by filter or any user related filter option. If it is a match, we represent the need as a milestone instead of a task in gantt chart.

milestone_filter must be a valid Filter string.

List of link names used to define task relationship, starts_with.

Default: None

Example

.. needgantt:: Starts_with example
   :tags: gantt_ex_starts_with
   :starts_with_links: starts_with

Result

@startuml

' Elements definition 

[Create example] as [ACT_CREATE_EX_SW] lasts 12 days
[Read example] as [ACT_READ_EX_SW] lasts 8 days
[Understand example] as [ACT_UNDERSTAND_EX_SW] lasts 12 days

' Element links definition 


' Deactivated, as currently supported by plantuml beta only
' Element completion definition 



' Element color definition 

[Create example] is colored in #FFCC00
[Read example] is colored in #FFCC00
[Understand example] is colored in #FFCC00


' Constraints definition 


' Constraints definition 

[ACT_READ_EX_SW] starts at [ACT_CREATE_EX_SW]'s end
[ACT_UNDERSTAND_EX_SW] starts at [ACT_READ_EX_SW]'s start

@enduml

Starts_with example

Show the needs used in the above example

Action: Create example ACT_CREATE_EX_SW ../_images/arrow-right-circle.svg
tags: gantt_ex_starts_with
duration: 12
links incoming: ACT_READ_EX_SW
Action: Read example ACT_READ_EX_SW ../_images/arrow-right-circle.svg
tags: gantt_ex_starts_with
duration: 8
links outgoing: ACT_CREATE_EX_SW
triggers directly: ACT_UNDERSTAND_EX_SW
Action: Understand example ACT_UNDERSTAND_EX_SW ../_images/arrow-right-circle.svg
tags: gantt_ex_starts_with
duration: 12
starts with: ACT_READ_EX_SW

List of link names used to define task relationship, starts_after.

Default: links

Example

.. needgantt:: Starts_after example
   :tags: gantt_ex_starts_after
   :starts_after_links: starts_after

Result

@startuml

' Elements definition 

[Create example] as [ACT_CREATE_EX_SA] lasts 12 days
[Read example] as [ACT_READ_EX_SA] lasts 8 days

' Element links definition 


' Deactivated, as currently supported by plantuml beta only
' Element completion definition 



' Element color definition 

[Create example] is colored in #FFCC00
[Read example] is colored in #FFCC00


' Constraints definition 


' Constraints definition 

[ACT_READ_EX_SA] starts at [ACT_CREATE_EX_SA]'s end

@enduml

Starts_with example

Show the needs used in the above example

Action: Create example ACT_CREATE_EX_SA ../_images/arrow-right-circle.svg
tags: gantt_ex_starts_after
duration: 12
triggers at end: ACT_READ_EX_SA
Action: Read example ACT_READ_EX_SA ../_images/arrow-right-circle.svg
tags: gantt_ex_starts_after
duration: 8
starts after: ACT_CREATE_EX_SA

List of link names used to define task relationship, ends_with.

Default: None

Example

.. needgantt:: Ends_with example
   :tags: gantt_ex_ends_with
   :ends_with_links: ends_with

Result

@startuml

' Elements definition 

[Create example] as [ACT_CREATE_EX_EW] lasts 12 days
[Read example] as [ACT_READ_EX_EW] lasts 8 days

' Element links definition 


' Deactivated, as currently supported by plantuml beta only
' Element completion definition 



' Element color definition 

[Create example] is colored in #FFCC00
[Read example] is colored in #FFCC00


' Constraints definition 


' Constraints definition 

[ACT_READ_EX_EW] ends at [ACT_CREATE_EX_EW]'s end

@enduml

Ends_with example

Show the needs used in the above example

Action: Create example ACT_CREATE_EX_EW ../_images/arrow-right-circle.svg
tags: gantt_ex_ends_with
duration: 12
triggers to end with: ACT_READ_EX_EW
Action: Read example ACT_READ_EX_EW ../_images/arrow-right-circle.svg
tags: gantt_ex_ends_with
duration: 8
ends with: ACT_CREATE_EX_EW

start_date

Optional start date for the gantt chart. We calculate all tasks and milestones dates based on the :start_date: option’s value.

Date format must be YYYY-MM-DD. Example: 2020-03-25

Example

.. needgantt:: Bug handling gantt
   :tags: gantt_example
   :milestone_filter: type == 'milestone'
   :start_date: 2020-03-25

Result

@startuml
Project starts the 25th of April 2020

' Elements definition 

[Find & Report bug] as [ACT_BUG] lasts 5 days
[Analyse bug] as [ACT_BUG_ANALYSE] lasts 7 days
[Create solution ticket] as [ACT_TICKET] lasts 3 days
[Work on solution ticket] as [ACT_TICKET_WORK] lasts 7 days
[Solution ticket closed] as [MS_TICKET_CLOSED] lasts 0 days
[Add solution to release plan] as [ACT_RELEASE_PLAN] lasts 1 days
[Deploy release] as [ACT_DEPLOY] lasts 2 days
[Test release] as [ACT_TEST] lasts 12 days
[Bug solved] as [MS_BUG_SOLVED] lasts 0 days

' Element links definition 


' Deactivated, as currently supported by plantuml beta only
' Element completion definition 

[Test release] is 80% completed


' Element color definition 

[Find & Report bug] is colored in #FFCC00
[Analyse bug] is colored in #FFCC00
[Create solution ticket] is colored in #FFCC00
[Work on solution ticket] is colored in #FFCC00
[Solution ticket closed] is colored in #FF3333
[Add solution to release plan] is colored in #FFCC00
[Deploy release] is colored in #FFCC00
[Test release] is colored in #FFCC00
[Bug solved] is colored in #FF3333


' Constraints definition 


' Constraints definition 

[ACT_BUG_ANALYSE] starts at [ACT_BUG]'s end
[ACT_TICKET] starts at [ACT_BUG_ANALYSE]'s end
[ACT_TICKET_WORK] starts at [ACT_TICKET]'s end
[MS_TICKET_CLOSED] happens at [ACT_TICKET_WORK]'s end
[ACT_RELEASE_PLAN] starts at [MS_TICKET_CLOSED]'s end
[ACT_DEPLOY] starts at [ACT_RELEASE_PLAN]'s end
[ACT_TEST] starts at [ACT_DEPLOY]'s end
[MS_BUG_SOLVED] happens at [ACT_TEST]'s end

@enduml

Bug handling gantt

timeline

Defines the timeline scale.

Allowed values: daily, weekly, monthly.

Default: daily

Works only, if you set start_date option.

Example

.. needgantt:: Bug handling gantt
   :tags: gantt_example
   :milestone_filter: type == 'milestone'
   :start_date: 2020-03-25
   :timeline: weekly

Result

@startuml
Project starts the 25th of April 2020

' Elements definition 

[Find & Report bug] as [ACT_BUG] lasts 5 days
[Analyse bug] as [ACT_BUG_ANALYSE] lasts 7 days
[Create solution ticket] as [ACT_TICKET] lasts 3 days
[Work on solution ticket] as [ACT_TICKET_WORK] lasts 7 days
[Solution ticket closed] as [MS_TICKET_CLOSED] lasts 0 days
[Add solution to release plan] as [ACT_RELEASE_PLAN] lasts 1 days
[Deploy release] as [ACT_DEPLOY] lasts 2 days
[Test release] as [ACT_TEST] lasts 12 days
[Bug solved] as [MS_BUG_SOLVED] lasts 0 days

' Element links definition 


' Deactivated, as currently supported by plantuml beta only
' Element completion definition 

[Test release] is 80% completed


' Element color definition 

[Find & Report bug] is colored in #FFCC00
[Analyse bug] is colored in #FFCC00
[Create solution ticket] is colored in #FFCC00
[Work on solution ticket] is colored in #FFCC00
[Solution ticket closed] is colored in #FF3333
[Add solution to release plan] is colored in #FFCC00
[Deploy release] is colored in #FFCC00
[Test release] is colored in #FFCC00
[Bug solved] is colored in #FF3333


' Constraints definition 


' Constraints definition 

[ACT_BUG_ANALYSE] starts at [ACT_BUG]'s end
[ACT_TICKET] starts at [ACT_BUG_ANALYSE]'s end
[ACT_TICKET_WORK] starts at [ACT_TICKET]'s end
[MS_TICKET_CLOSED] happens at [ACT_TICKET_WORK]'s end
[ACT_RELEASE_PLAN] starts at [MS_TICKET_CLOSED]'s end
[ACT_DEPLOY] starts at [ACT_RELEASE_PLAN]'s end
[ACT_TEST] starts at [ACT_DEPLOY]'s end
[MS_BUG_SOLVED] happens at [ACT_TEST]'s end

@enduml

Bug handling gantt

no_color

We derive the tasks and milestone color from the need-type configuration, else we use the default PlantUML colors.

@startuml

' Elements definition 

[Find & Report bug] as [ACT_BUG] lasts 5 days
[Analyse bug] as [ACT_BUG_ANALYSE] lasts 7 days
[Create solution ticket] as [ACT_TICKET] lasts 3 days
[Work on solution ticket] as [ACT_TICKET_WORK] lasts 7 days
[Solution ticket closed] as [MS_TICKET_CLOSED] lasts 0 days
[Add solution to release plan] as [ACT_RELEASE_PLAN] lasts 1 days
[Deploy release] as [ACT_DEPLOY] lasts 2 days
[Test release] as [ACT_TEST] lasts 12 days
[Bug solved] as [MS_BUG_SOLVED] lasts 0 days

' Element links definition 


' Deactivated, as currently supported by plantuml beta only
' Element completion definition 

[Test release] is 80% completed


' Element color definition 

' Color support deactivated via flag
' Constraints definition 


' Constraints definition 

[ACT_BUG_ANALYSE] starts at [ACT_BUG]'s end
[ACT_TICKET] starts at [ACT_BUG_ANALYSE]'s end
[ACT_TICKET_WORK] starts at [ACT_TICKET]'s end
[MS_TICKET_CLOSED] happens at [ACT_TICKET_WORK]'s end
[ACT_RELEASE_PLAN] starts at [MS_TICKET_CLOSED]'s end
[ACT_DEPLOY] starts at [ACT_RELEASE_PLAN]'s end
[ACT_TEST] starts at [ACT_DEPLOY]'s end
[MS_BUG_SOLVED] happens at [ACT_TEST]'s end

@enduml

Bug handling gantt

duration_option

Defines the option to use as the duration value. We interpret the value in days, no matter what the name of the option is.

You can set the duration option globally by using needs_duration_option in conf.py.

Default: duration

Example

.. needgantt:: Duration example
   :tags: gantt_ex_duration
   :duration_option: hours

Result

@startuml

' Elements definition 

[Create example] as [ACT_CREATE_EX] lasts 12 days
[Read example] as [ACT_READ_EX] lasts 3 days

' Element links definition 


' Deactivated, as currently supported by plantuml beta only
' Element completion definition 



' Element color definition 

[Create example] is colored in #FFCC00
[Read example] is colored in #FFCC00


' Constraints definition 


' Constraints definition 

[ACT_READ_EX] starts at [ACT_CREATE_EX]'s end

@enduml

Duration example

Show the needs used in the above example

Action: Create example ACT_CREATE_EX ../_images/arrow-right-circle.svg
tags: gantt_ex_duration
hours: 12
links incoming: ACT_READ_EX
Action: Read example ACT_READ_EX ../_images/arrow-right-circle.svg
tags: gantt_ex_duration
hours: 3
duration: 100
links outgoing: ACT_CREATE_EX

duration option gets ignored in the above needgantt.

completion_option

Defines the option to use as the completion value. We interpret the value in percentage.

You can set the completion option globally by using needs_completion_option in conf.py.

Default: completion

Example

.. needgantt:: Completion example
   :tags: gantt_ex_completion
   :completion_option: amount

Result

@startuml

' Elements definition 

[Create example] as [ACT_CREATE_EX_C] lasts 12 days
[Read example] as [ACT_READ_EX_C] lasts 12 days

' Element links definition 


' Deactivated, as currently supported by plantuml beta only
' Element completion definition 

[Create example] is 90% completed
[Read example] is 40% completed


' Element color definition 

[Create example] is colored in #FFCC00
[Read example] is colored in #FFCC00


' Constraints definition 


' Constraints definition 

[ACT_READ_EX_C] starts at [ACT_CREATE_EX_C]'s end

@enduml

Completion example

Show the needs used in the above example

Action: Create example ACT_CREATE_EX_C ../_images/arrow-right-circle.svg
tags: gantt_ex_completion
amount: 90%
duration: 12
links incoming: ACT_READ_EX_C
Action: Read example ACT_READ_EX_C ../_images/arrow-right-circle.svg
tags: gantt_ex_completion
amount: 40
duration: 12
links outgoing: ACT_CREATE_EX_C

common filters