Skip to content

Commit 37cb93c

Browse files
LisaBockLisaBock
authored
Merge pull request #252 from ESMValGroup/add_quickstart_method
Add quickstart method
2 parents ebca6bb + cc47081 commit 37cb93c

File tree

6 files changed

+121
-6
lines changed

6 files changed

+121
-6
lines changed

_episodes/01-introduction.md renamed to _episodes/00-introduction.md

File renamed without changes.

‎_episodes/01-quickstart.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
---
2+
title: "Quickstart guide"
3+
teaching: 2
4+
exercises: 8
5+
questions:
6+
7+
- "What is the purpose of the quickstart guide?"
8+
- "How do I load and check the ESMValTool environment?"
9+
- "How do I configure ESMValTool?"
10+
- "How do I run a recipe?"
11+
12+
objectives:
13+
14+
- "Understand the purpose of the quickstart guide"
15+
- "Load and check the ESMValTool environment"
16+
- "Configure ESMValTool"
17+
- "Run a recipe"
18+
19+
keypoints:
20+
21+
- "The purpose of the quickstart guide is to enable a user of ESMValTool
22+
to run ESMValTool as quickly as possible without having to go through the
23+
whole tutorial"
24+
- "Use the `module load` command to load the ESMValTool environment,
25+
see the [installation]({{ page.root }}{% link _episodes/02-installation.md %})
26+
episode for more details and use `esmvaltool --help` to check the ESMValTool
27+
environment"
28+
- "Use `esmvaltool config get_config_user` to create the ESMValTool user
29+
configuration file"
30+
- "Use `esmvaltool run <recipe>.yml` to run a recipe"
31+
---
32+
>
33+
> This quickstart guide is compatible with ESMValTool v2.6.0.
34+
{: .callout}
35+
36+
> ## What is the purpose of the quickstart guide?
37+
>
38+
> - The purpose of the quickstart guide is to enable a user of ESMValTool to
39+
> run ESMValTool as quickly as possible by making the bare minimum number of
40+
> changes.
41+
{: .discussion}
42+
43+
> ## How do I load and check the ESMValTool environment?
44+
>
45+
> - For this quickstart guide, an assumption is made that ESMValTool has
46+
> already been installed at the site where ESMValTool will be run. If this is
47+
> not the case, see the [Installation][lesson-installation] episode in this
48+
> tutorial.
49+
>
50+
> - Load the ESMValTool environment by following the instructions at
51+
> [ESMValTool: Pre-installed versions on HPC clusters / other
52+
> servers][activate-environment].
53+
>
54+
> - Check the ESMValTool environment by accessing the help for ESMValTool:
55+
>
56+
> ~~~
57+
> esmvaltool --help
58+
> ~~~
59+
> {: .language-bash}
60+
{: .challenge}
61+
62+
> ## How do I configure ESMValTool?
63+
>
64+
> - Create the ESMValTool user configuration file (the file is written by
65+
> default to `~/.esmvaltool/config-user.yml`):
66+
>
67+
> ~~~
68+
> esmvaltool config get_config_user
69+
> ~~~
70+
> {: .language-bash}
71+
>
72+
> - Edit the ESMValTool user configuration file using your favourite text editor
73+
> to uncomment the lines relating to the site where ESMValTool will be run.
74+
>
75+
> - For more details about the ESMValTool user configuration file see the
76+
> [Configuration][lesson-configuration] episode in this tutorial.
77+
{: .challenge}
78+
79+
> ## How do I run a recipe?
80+
>
81+
> - Run the example Python recipe:
82+
>
83+
> ~~~
84+
> esmvaltool run examples/recipe_python.yml
85+
> ~~~
86+
> {: .language-bash}
87+
>
88+
> - Wait for the recipe to complete. If the recipe completes successfully, the
89+
> last line printed to screen at the end of the log will look something like:
90+
>
91+
> ~~~
92+
> YYYY-MM-DD HH:mm:SS, NNN UTC [NNNNN] INFO Run was successful
93+
> ~~~
94+
> {: .language-bash}
95+
>
96+
> - View the output of the recipe by opening the HTML file produced by
97+
> ESMValTool (the location of this file is printed to screen near the end of
98+
> the log):
99+
>
100+
> ~~~
101+
> YYYY-MM-DD HH:mm:SS, NNN UTC [NNNNN] INFO Wrote recipe output to:
102+
> file:///$HOME/esmvaltool_output/recipe_python_<date>_<time>/index.html
103+
> ~~~
104+
> {: .language-bash}
105+
>
106+
> - For more details about running recipes see the
107+
> [Running your first recipe][lesson-recipe] episode in this tutorial.
108+
{: .challenge}
109+
110+
{% include links.md %}

‎_episodes/04-recipe.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,8 @@ run your first recipe, look at the recipe output, and make small modifications.
2323
## Running an existing recipe
2424

2525
The recipe format has briefly been introduced in the
26-
[Introduction]({{ page.root }}{% link _episodes/01-introduction.md %}) episode.
27-
To see all the recipes that are shipped with ESMValTool, type
26+
[Introduction][lesson-introduction] episode. To see all the
27+
recipes that are shipped with ESMValTool, type
2828

2929
```bash
3030
esmvaltool recipes list
@@ -437,3 +437,5 @@ ESMValTool.
437437
> >
438438
> {: .solution}
439439
{: .challenge}
440+
441+
{% include links.md %}

‎_includes/links.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
{% include base_path.html %}
2+
[activate-environment]: https://docs.esmvaltool.org/en/latest/quickstart/installation.html#pre-installed-versions-on-hpc-clusters-other-servers
23
[cc-by-human]: https://creativecommons.org/licenses/by/4.0/
34
[cc-by-legal]: https://creativecommons.org/licenses/by/4.0/legalcode
45
[ci]: http://communityin.org/
@@ -28,9 +29,13 @@
2829
[lc-lessons]: https://librarycarpentry.org/lessons/
2930
[lesson-aio]: {{ relative_root_path }}{% link aio.md %}
3031
[lesson-coc]: {{ relative_root_path }}{% link CODE_OF_CONDUCT.md %}
32+
[lesson-configuration]: {{ relative_root_path }}{% link _episodes/03-configuration.md %}
3133
[lesson-example]: https://carpentries.github.io/lesson-example/
34+
[lesson-installation]: {{ relative_root_path }}{% link _episodes/02-installation.md %}
35+
[lesson-introduction]: {{ relative_root_path }}{% link _episodes/00-introduction.md %}
3236
[lesson-license]: {{ relative_root_path }}{% link LICENSE.md %}
3337
[lesson-mainpage]: {{ relative_root_path }}{% link index.md %}
38+
[lesson-recipe]: {{ relative_root_path }}{% link _episodes/04-recipe.md %}
3439
[lesson-reference]: {{ relative_root_path }}{% link reference.md %}
3540
[lesson-setup]: {{ relative_root_path }}{% link setup.md %}
3641
[manage-environments]: https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html

‎bin/lesson_initialize.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
'CONTRIBUTING.md',
1313
'README.md',
1414
'_config.yml',
15-
os.path.join('_episodes', '01-introduction.md'),
15+
os.path.join('_episodes', '00-introduction.md'),
1616
os.path.join('_extras', 'about.md'),
1717
os.path.join('_extras', 'figures.md'),
1818
os.path.join('_extras', 'guide.md'),

‎index.md‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,7 @@ causes and effects of model biases and inter-model spread within the CMIP model
1212
ensemble.
1313

1414
This tutorial is structured into ``basic`` and ``advanced`` topics such that episodes
15-
starting from the
16-
[Introduction]({{ page.root }}{% link _episodes/01-introduction.md %}) up to
17-
the episode on
15+
starting from the [Introduction][lesson-introduction] up to the episode on
1816
[Conclusion of the basic tutorial]({{ page.root }}{% link _episodes/05-conclusions.md %})
1917
all cover basic topics and can be done in one sitting.
2018

0 commit comments

Comments
 (0)