CLIMADA Tutorial Template#
Content#
Why tutorials#
Main goal:
The main goal of the tutorials is it to give a complete overview on:
essential CLIMADA components
introduce newly developed modules and features
More specifically, tutorials should introduce CLIMADA users to the core functionalities and modules and guide users in their application. Hence, each new module created needs to be accompanied with a tutorial. The following sections give an overview of the basic structure desired for CLIMADA tutorials.
Important:
A tutorial needs to be included with the final pull request for every new feature.
Basic structure#
Every tutorial should cover the following main points. Additional features characteristic to the modules presented can and should be added as seen fit.
Introduction#
What is the feature presented?
Briefly describe the feature and introduce how it’s presented in the CLIMADA framework.What is its data structure?
Present and overview (in the form of a table for example) of where the feature is built into CLIMADA. What class does it belong to, what are the variables of the feature, what is their data structure.Table of content:
How is this tutorial structured?
Illustration of feature functionality and application#
Walk users through the core functions of the module and illustrate how the feature can be used. This obviously is dependent on the feature itself. A few core points should be considered when creating the tutorial:
SIZE MATTERS!
each notebook as a total should not exceed the critical (yet vague) size of “a couple MB”
keep the size of data you use as examples in the tutorial in mind
we aim for computational efficiency
a lean, well-organized, concise notebook is more informative than a long, messy all-encompassing one.
follow the general CLIMADA naming convention for the notebook. For example: “climada_hazard_TropCyclone.ipynb”
Good examples#
The following examples can be used as templates and inspiration for your tutorial:
Use only Markdown for headers and table of content#
To create headers or a table of content with links, avoid using hmtl and prefer instead purely Markdown syntax. Follow Markdown conventions in the Markdown Guide and the following key points presented in the section below to know how to use correct Markdown syntax which is consistent with the rest of CLIMADA documentation. If in doubt, check existing tutorials to see how it is done.
Headers#
To structure your tutorial, use headers of different levels to create sections and subsections.
To create an header, write the symbol (#) before your header name
‘#’ : create a header of level 1
‘##’ : create a header of level 2
‘###’ : create a header of level 3
‘####’ : create a header of level 4
The title of the tutorial should be of level 1 (#), should have its own cell, and should be the first cell of the notebook.
Table of content#
The second cell of the notebook should be the table of content and should have a header name ‘Content’ and a level of 2 (##).
To create the table of content, avoid using numbers to list the different sections, prefer instead simple dots by using ‘-’ :
Instead of numbers :
Additionally, the table of content should only contain headers of level 2 (##).
To create a link from the table of content to a certain section of the tutorial, write [Name of your choice] followed by (#Exactly-the-header-name-you-want-to-direct-the-user-to).
Remember to fill white spaces with ‘-’ and that links to headers are case sensitive! (#This-paRt-Is-CaSe-sEnSitIve).
See the syntax of the example below to create a table of content.
Input:#
## Content
- [My first header](#My-first-header)
- [My second header](#My-second-header)
- [My third header](#My-third-header)