Skip to content
Back to top
View this page
Edit this page

# needgantt

Added in version 0.5.5.

`needgantt` adds a gantt-chart to your documentation.

Example 1

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

Bug handling gantt

Show used needs for above example

Action: Find & Report bug ACT_BUG
tags: gantt_example duration: 5 links incoming: ACT_BUG_ANALYSE

Action: Analyse bug ACT_BUG_ANALYSE
tags: gantt_example duration: 7 links outgoing: ACT_BUG links incoming: ACT_TICKET

Action: Create solution ticket ACT_TICKET
tags: gantt_example duration: 3 links outgoing: ACT_BUG_ANALYSE links incoming: ACT_TICKET_WORK

Action: Work on solution ticket ACT_TICKET_WORK
tags: gantt_example duration: 7 links outgoing: ACT_TICKET links incoming: MS_TICKET_CLOSED

Milestone: Solution ticket closed MS_TICKET_CLOSED
tags: gantt_example links outgoing: ACT_TICKET_WORK links incoming: ACT_RELEASE_PLAN

Action: Add solution to release plan ACT_RELEASE_PLAN
tags: gantt_example duration: 1 links outgoing: MS_TICKET_CLOSED links incoming: ACT_DEPLOY

Action: Deploy release ACT_DEPLOY
tags: gantt_example duration: 2 links outgoing: ACT_RELEASE_PLAN links incoming: ACT_TEST

Action: Test release ACT_TEST
tags: gantt_example duration: 12 completion: 80% links outgoing: ACT_DEPLOY links incoming: MS_BUG_SOLVED

Milestone: Bug solved MS_BUG_SOLVED
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:

- starts with: see starts_with_links

- starts after: see starts_after_links

- ends with: see ends_with_links

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.

### starts_with_links

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

Default: None

Example 2

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

Starts_with example

Show used needs for above example

Action: Create example ACT_CREATE_EX_SW
tags: gantt_ex_starts_with duration: 12 links incoming: ACT_READ_EX_SW

Action: Read example ACT_READ_EX_SW
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
tags: gantt_ex_starts_with duration: 12 starts with: ACT_READ_EX_SW

### starts_after_links

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

Default: links

Example 3

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

Starts_after example

Show the needs used in the above example

Action: Create example ACT_CREATE_EX_SA
tags: gantt_ex_starts_after duration: 12 triggers at end: ACT_READ_EX_SA

Action: Read example ACT_READ_EX_SA
tags: gantt_ex_starts_after duration: 8 starts after: ACT_CREATE_EX_SA

### ends_with_links

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

Default: None

Example 4

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

Ends_with example

Show the needs used in the above example

Action: Create example ACT_CREATE_EX_EW
tags: gantt_ex_ends_with duration: 12 triggers to end with: ACT_READ_EX_EW

Action: Read example ACT_READ_EX_EW
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 5

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

Bug handling gantt

### timeline

Defines the timeline scale.

Allowed values: `daily`, `weekly`, `monthly`.

Default: `daily`

Works only, if you set start_date option.

Example 6

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

Bug handling gantt

### no_color

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

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 7

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

Duration example

Show the needs used in the above example

Action: Create example ACT_CREATE_EX
tags: gantt_ex_duration hours: 12 links incoming: ACT_READ_EX

Action: Read example ACT_READ_EX
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 8

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

Completion example

Show the needs used in the above example

Action: Create example ACT_CREATE_EX_C
tags: gantt_ex_completion amount: 90% duration: 12 links incoming: ACT_READ_EX_C

Action: Read example ACT_READ_EX_C
tags: gantt_ex_completion amount: 40 duration: 12 links outgoing: ACT_CREATE_EX_C

### common filters

- status

- tags

- types

- filter