Usage Documentation

Roadmap Anatomy

Roadmap generated by Roadmapper consists of several components as depicted below:

• Title: This is the title of the roadmap.
• Subtitle: This is the subtitle of the roadmap.
• Timeline: This section shows roadmap timeline. Timeline consists of Year and Items. Timeline items can be configured to show different time scale as below:
  • weekly
  • monthly
  • quarterly
  • half-yearly
  • yearly
• Group: This is used to group all tasks together. Every task belongs to a group.
• Task: This is used to show task or activity for a given start and end date.
• Parallel Task: This is used to show a another task or activity on the same line.
• Milestone: This is used to show a 'diamond' shape symbol to denote a milestone. Milestone is optional.
• Footer: This is the footer of the roadmap. Footer is optional.
• Marker: This is the current date marker

Steps to create a roadmap

Step 1: Import Roadmap and TimelineMode package

from roadmapper.roadmap import Roadmap
from roadmapper.timelinemode import TimelineMode

Step 2: Create a Roadmap instance.

my_roadmap = Roadmap(width=500, height=300)

In the Roadmap constructor method, specify the roadmap canvas size. The measurement is in pixel. Optionally, you could also specify:

• auto_height: Option to let roadmapper to automatically resize the height of the generated roadmap image. Default is set to True
• colour_theme: There are currently five colour scheme to choose from, namely: DEFAULT, GREYWOOF, ORANGEPEEL, GREENTURTLE, BLUEMOUNTAIN. Setting colour at component level will over the colour theme settings.
• show_marker: Set the current date marker on or off on the roadmap. Default is set to True

my_roadmap = Roadmap(width=500, height=300, colour_theme="BLUEMOUNTAIN", show_marker=True)

Step 3: Configure roadmap title, subtitle and timeline

my_roadmap.set_title("My Roadmap")
my_roadmap.set_subtitle("Matariki Technologies Inc.")
my_roadmap.set_timeline(mode=TimelineMode.MONTHLY, start="2022-11-14", number_of_items=6)

Call set_title() method to specify the text to be displayed as title. Optionally, you can specify font, font size, and font colour if you want to change the style.

my_roadmap.set_title(
    text="My Roadmap", 
    font="Arial.ttf", 
    font_size=18, 
    font_colour="Black",
)

Call set_subtitle() method to specify the text to be display as subtitle. Optionally, you can specify font, font size, and font colour if you want to change the style.

my_roadmap.set_subtitle(
    "Matariki Technologies Inc.",
    font="Arial.ttf", 
    font_size=12, 
    font_colour="Black",
)

Call set_timeline() method to configure the roadmap timeline. The timeline changes depending on the mode, start date and number of items to be display on the canvas. Additional parameters can be passed in to configure the font, font size, font colour and fill colour.

Note:

• Roadmapper uses uses ISO 8601 standard for date representation. All dates must be entered in "YYYY-MM-DD" format.
• font, font_size, font_colour, fill_colour are depreciated in v1.0.0. To change timeline font, font size, font colour and fill colour, you have to specify the settings for both year and item separately:

my_roadmap.set_timeline(
    mode=TimelineMode.MONTHLY, 
    start="2022-11-14", 
    number_of_items=6, 
    show_generic_dates=False
    font="Arial.ttf", 
    year_font_size=18, 
    year_font_colour="Black"
    year_fill_colour="Lightblue",
    item_font="Arial.ttf", 
    item_font_size=18, 
    item_font_colour="Black"
    item_fill_colour="Lightblue"
)

year_font_colour, year_fill_colour, item_font_colour and item_fill_colour support web colour name (e.g. Red) or hex code (e.g. #FF0000) Supported TimelineMode includes:

• TimelineMode.WEEKLY
• TimelineMode.MONTHLY (default)
• TimelineMode.QUARTERLY
• TimelineMode.HALF_YEAR
• TimelineMode.YEARLY

Set show_generic_dates to True if you want to display generic non specific dates like Month 1, Month 2, etc instead of actual date like February 2023
When timeline mode is set to "TimelineMode.WEEKLY", you can also set show_first_day_of_week to True if you want to display first day of week instead of W1, W2, etc.

Step 4: Add group and task(s) to the roadmap

group = my_roadmap.add_group("Development")
group.add_task("Activity 1", "2022-12-01", "2023-02-10") 

You can add more tasks by calling add_task() method multiple time.

group.add_task("Activity 2", "2023-01-11", "2023-03-20")
group.add_task("Activity 3", "2023-01-21", "2023-06-30")

Step 5: Configure footer

my_roadmap.set_footer("Generated by Roadmapper")

Step 6: Render the roadmap

my_roadmap.draw()

Step 7: Save the roadmap to a PNG file format

my_roadmap.save("my_roadmap.png")

Output

How to display multiple tasks or activities on the same line?

To display tasks on the same line as other tasks, call add_parallel_task() method as shown below.

group = my_roadmap.add_group("Core Features")
task = group.add_task("Feature 1", "2022-12-01", "2023-02-10")
task.add_parallel_task("Feature 2", "2023-03-01", "2023-04-30")

Remember to use task instance returned from add_task() method to invoke add_parallel_task() method. The code example basically shows "Feature 2" on the same parallel line as "Feature 1"

How to display milestone on tasks?

To display a milestone on task. call add_milestone() method.

task = group.add_task("Feature 4", "2023-01-21", "2023-05-30")
task.add_milestone("Milestone 1", "2023-05-31")

Remember to use 'task' instance returned from add_task() method to invoke add_milestone() method. The code example shows a milestone on 31 May 2023 with the label "Milestone 1"

How to show generic dates instead of actual date?

To show generic date such as 'Month 1, Month 2, etc", add show_generic_dates=True to the set_timeline() method parameters.

my_roadmap.set_timeline(
    mode=TimelineMode.MONTHLY, 
    start="2022-11-14", 
    number_of_items=6, 
    show_generic_dates=True
)

How to show current date marker 🔽?

To display the current date marker, add show_marker=True to the Roadmap() constructor parameters.

my_roadmap = Roadmap(4100, 2000, show_marker=True)

See the sample roadmap in the gallery

How to use the built-in colour scheme?

my_roadmap = Roadmap(4100, 2000, colour_theme="ORANGEPEEL")

There are five colour themes added into version 0.2.2:

• "DEFAULT"
• "BLUEMOUNTAIN"
• "GREENTURTLE"
• "ORANGEPEEL"
• "GREYWOOF"

See the sample roadmaps in the gallery

How to add sub title to the roadmap?

To add sub title beneath the main title, just call the set_subtitle() method.

    my_roadmap.set_title("ROADMAP EXAMPLE 2022/2023")
    my_roadmap.set_subtitle("This is a subtitle")

How to let roadmapper auto adjust roadmap height?

To let roadmapper to automatically resize the height, add auto_height=True to the Roadmap constructor parameters.

my roadmap = Roadmap(
        1200,
        1400,
        auto_height=True,
    )

How to add logo to the roadmap?

To add logo, call add_logo() method and specify the display position.

my_roadmap.add_logo("matariki-tech-logo.png", position="top-right", width=50, height=50

• position can be one of the following values
  • top-left
  • top-centre
  • top-right
  • bottom-left
  • bottom-centre
  • bottom-right
• width and height are used to resize the logo