|
17 | 17 | "\n", |
18 | 18 | "- [Why tutorials](#Why-tutorials)\n", |
19 | 19 | "- [Basic structure](#Basic-structure)\n", |
20 | | - "- [Good examples](#Good-examples)" |
| 20 | + "- [Good examples](#Good-examples)\n", |
| 21 | + "- [Use only Markdown for headers and table of content](#Use-only-Markdown-for-headers-and-table-of-content)" |
21 | 22 | ] |
22 | 23 | }, |
23 | 24 | { |
|
27 | 28 | "source": [ |
28 | 29 | "## Why tutorials\n", |
29 | 30 | "\n", |
30 | | - "**Main goal:**<br>\n", |
| 31 | + "**Main goal:**\n", |
| 32 | + "\n", |
31 | 33 | "The main goal of the tutorials is it to give a complete overview on:\n", |
32 | 34 | "\n", |
33 | 35 | "- essential CLIMADA components\n", |
34 | 36 | "- introduce newly developed modules and features\n", |
35 | 37 | "\n", |
36 | 38 | "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.\n", |
37 | 39 | "\n", |
38 | | - "**Important:**<br>\n", |
| 40 | + "**Important:**\n", |
| 41 | + "\n", |
39 | 42 | "A tutorial needs to be included with the final pull request for every new feature." |
40 | 43 | ] |
41 | 44 | }, |
|
85 | 88 | " - keep the size of data you use as examples in the tutorial in mind\n", |
86 | 89 | " - we aim for computational efficiency\n", |
87 | 90 | " - a lean, well-organized, concise notebook is more informative than a long, messy all-encompassing one.\n", |
88 | | - "\n", |
89 | | - "- follow the general CLIMADA naming convention for the notebook. For example: \"climada_hazard_TropCyclone.ipynb\"\n", |
90 | | - "" |
| 91 | + "- follow the general CLIMADA naming convention for the notebook. For example: \"climada_hazard_TropCyclone.ipynb\"" |
91 | 92 | ] |
92 | 93 | }, |
93 | 94 | { |
|
99 | 100 | "\n", |
100 | 101 | "The following examples can be used as templates and inspiration for your tutorial:\n", |
101 | 102 | "\n", |
102 | | - "- https://github.com/CLIMADA-project/climada_python/blob/main/doc/tutorial/climada_entity_Exposures.ipynb\n", |
103 | | - "- https://github.com/CLIMADA-project/climada_python/blob/main/doc/tutorial/climada_hazard_Hazard.ipynb" |
| 103 | + "- [Exposure tutorial](https://github.com/CLIMADA-project/climada_python/blob/main/doc/tutorial/climada_entity_Exposures.ipynb)\n", |
| 104 | + "- [Hazard tutorial](https://github.com/CLIMADA-project/climada_python/blob/main/doc/tutorial/climada_hazard_Hazard.ipynb)" |
| 105 | + ] |
| 106 | + }, |
| 107 | + { |
| 108 | + "attachments": {}, |
| 109 | + "cell_type": "markdown", |
| 110 | + "metadata": {}, |
| 111 | + "source": [ |
| 112 | + "## Use only Markdown for headers and table of content\n", |
| 113 | + "\n", |
| 114 | + "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](https://www.markdownguide.org/basic-syntax/) 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." |
| 115 | + ] |
| 116 | + }, |
| 117 | + { |
| 118 | + "attachments": {}, |
| 119 | + "cell_type": "markdown", |
| 120 | + "metadata": {}, |
| 121 | + "source": [ |
| 122 | + "### Headers\n", |
| 123 | + "\n", |
| 124 | + "To structure your tutorial, use headers of different levels to create sections and subsections.\n", |
| 125 | + "\n", |
| 126 | + "To create an header, write the symbol (#) before your header name\n", |
| 127 | + "\n", |
| 128 | + "**'#'** : create a header of level 1\n", |
| 129 | + "\n", |
| 130 | + "**'##'** : create a header of level 2 \n", |
| 131 | + "\n", |
| 132 | + "**'###'** : create a header of level 3 \n", |
| 133 | + "\n", |
| 134 | + "**'####'** : create a header of level 4 \n", |
| 135 | + "\n", |
| 136 | + "The title of the tutorial should be of level 1 (#), should have its own cell, and should be the first cell of the notebook." |
| 137 | + ] |
| 138 | + }, |
| 139 | + { |
| 140 | + "attachments": {}, |
| 141 | + "cell_type": "markdown", |
| 142 | + "metadata": {}, |
| 143 | + "source": [ |
| 144 | + "## Table of content\n", |
| 145 | + "\n", |
| 146 | + "The second cell of the notebook should be the table of content and should have a header name *'Content'* and a level of 2 (##).\n", |
| 147 | + "\n", |
| 148 | + "To create the table of content, avoid using numbers to list the different sections, prefer instead simple dots by using '**-**' :\n", |
| 149 | + "\n", |
| 150 | + "\n", |
| 151 | + "-\n", |
| 152 | + "-\n", |
| 153 | + "\n", |
| 154 | + "\n", |
| 155 | + "Instead of numbers :\n", |
| 156 | + "\n", |
| 157 | + "1.\n", |
| 158 | + "2.\n", |
| 159 | + "\n", |
| 160 | + "\n", |
| 161 | + "Additionally, the table of content should only contain headers of level 2 (##).\n", |
| 162 | + "\n", |
| 163 | + "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).\n", |
| 164 | + "\n", |
| 165 | + "Remember to fill white spaces with '-' and that links to headers are case sensitive! (#This-paRt-Is-CaSe-sEnSitIve).\n", |
| 166 | + "\n", |
| 167 | + "See the syntax of the example below to create a table of content. \n" |
| 168 | + ] |
| 169 | + }, |
| 170 | + { |
| 171 | + "attachments": {}, |
| 172 | + "cell_type": "markdown", |
| 173 | + "metadata": {}, |
| 174 | + "source": [ |
| 175 | + "### Input:\n", |
| 176 | + "\n", |
| 177 | + "```markdown\n", |
| 178 | + "## Content\n", |
| 179 | + "\n", |
| 180 | + "- [My first header](#My-first-header)\n", |
| 181 | + "- [My second header](#My-second-header)\n", |
| 182 | + "- [My third header](#My-third-header)\n", |
| 183 | + "\n", |
| 184 | + "```\n", |
| 185 | + "\n", |
| 186 | + "### Output:\n", |
| 187 | + "\n", |
| 188 | + "## Content\n", |
| 189 | + "\n", |
| 190 | + "- [My first header](#My-first-header)\n", |
| 191 | + "- [My second header](#My-second-header)\n", |
| 192 | + "- [My third header](#My-third-header)" |
104 | 193 | ] |
105 | 194 | } |
106 | 195 | ], |
|
0 commit comments