Merge pull request #56 from ESMValGroup/setup_md

Setup md

Author: sverhoeven

index.md

@@ -35,19 +35,8 @@ independently.
 
 > ## Prerequisites
 >
-> *Minimal requirements:*
->
-> - Basic understanding of your preferred command line interface (ie a bash
->   terminal)
-> - Laptop/desktop with
->   [(mini)conda](https://docs.conda.io/en/latest/miniconda.html) installed
-> - Access to CMIP data
->
-> *Optional, but useful:*
->
-> - Basic understanding of git
-> - Access to a suitable computing system (eg CEDA-Jasmin, DKRZ-Mistral)
-> - GitHub account
+> The prerequisites for the tutorial are listed on the
+> [tutorial setup page]({{ page.root }}{% link setup.md %}).
 >
 {: .prereq}
 

setup.md

@@ -5,23 +5,19 @@ title: Preparations for participating in the tutorial
 This page includes some information on how to prepare for participating in this tutorial.
 
 > ## Prerequisites
-> The prerequisites for the tutorial are listed on the
-> [tutorials home page]({{ page.root}}[% index.md %})
->  and are also eproduced here:
-> - Basic understanding of git (optional)
 >
-> - Basic understanding of your preferred command line interface (ie a bash terminal)
+> *Minimal requirements:*
+>  - Basic understanding of your preferred command line interface (ie a bash terminal)
+>  - Access to CMIP data
 >
-> - Access to CMIP data
->
-> - Access to a suitable computing system (eg Jasmin, DLR machine)
->
-> - Github account (optional)
+> *Optional, but useful:*
+>  - Basic understanding of git
+>  - Access to a suitable computing system (eg CEDA-Jasmin, DKRZ-Mistral)
+>  - GitHub account
 {: .prereq}
 
 
-## Optional tutorials to be prepared to use ESMValTool
-
+## Command line & git tutorials
 
 We typically use the command line to interact with ESMValTool. While most of us
 are likely to have experience with the command line, novices may want to work
@@ -40,7 +36,6 @@ ESMValTool code.
 
 
 
-
 ## Access to CMIP and Observational data and a suitable compute cluster
 
 To complete this tutorial and use ESMValTool, you will need access to data in a
@@ -56,28 +51,25 @@ Intercomparison Project
 locally stored on disk and accessible directly by the tool. Similarly,
 observational data would also be available at these sites.
 
-Here are a few options
-for compute clusters with ESGF nodes:
+Here are a few options for compute clusters with ESGF nodes:
 
-- CEDA-Jasmin (UK):
-- DKRZ (Germany):
-- ETHZ (Switzerland):
+- [CEDA-Jasmin (UK)](#ceda-jasmin)
+- [DKRZ (Germany)](#dkrz)
 
 A full list of all ESGF nodes is available
 [here](https://esgf.llnl.gov/nodes.html).
 
-
 If you're running on a computing cluster without an ESGF node, such as your
-local machine, or your institue machine, you will most likely have to make a
+local machine, or your institute machine, you will most likely have to make a
 local copy of the data that you need.
 
 If necessary, data can be downloaded using the
 [synda tool](https://prodiguer.github.io/synda/index.html).
 
-
-
 ### CEDA-Jasmin
 
+Please skip this section if you are not going to use JASMIN and go [here](#Github-account-(Advanced)).
+
 If you do not already have an account on JASMIN, then request an account as soon
 as possible. Please follow [these instructions on how to create a Jasmin
 account](https://help.jasmin.ac.uk/article/4435-get-a-jasmin-account-portal)
@@ -100,7 +92,6 @@ Note that you have only created an account for the web-interface. To log into
 the jasmin machine and do work, you'll need to create a login account too using
 [this page](https://help.jasmin.ac.uk/article/161-get-login-account).
 
-
 #### Access to data on JASMIN
 
 Please request access to the working groups:
@@ -147,7 +138,6 @@ research centres). You may need a VPN if you wish to connect from your home
 network.
 
 
-
 Please request access to the working groups:
 - [esmeval working
   group](https://accounts.jasmin.ac.uk/services/group_workspaces/esmeval)
@@ -163,6 +153,7 @@ access the BADC archives via JASMIN. Some CMIP5 data sets such as MIROC are not
 accessible by default and special permission has to be requested to access them
 via [the CEDA catalogue page](https://catalogue.ceda.ac.uk/).
 
+
 #### Test your Setup
 
 Log into jasmin-login:
@@ -191,9 +182,13 @@ Note that the JASMIN is only open to certain locations (mostly universities, and
 research centres). You may need a VPN if you wish to connect from your home
 network.
 
+Congratulations! Please go here [here](#gitHub-account-(advanced)) next.
+
 
 ### DKRZ
 
+Please skip this section if you are not going to use DKRZ and go [here](#github-account-(advanced)).
+
 If you do not already have an account at the DKRZ, then
 [register](https://luv.dkrz.de/projects/newuser/) as soon as possible. You could
 find a short introduction on how to get started at DKRZ
@@ -240,17 +235,21 @@ ssh -X <user-account>@mistralpp.dkrz.de
 Data storage:
 - Personal data: home directory (24GiB)
 - Project data: /work/<project>/<user-account>
-- Temporary data: scratch directory on /scratch/*/<user-account> is
+- Temporary data: scratch directory on /scratch/\*/<user-account> is
   automatically deleted after 14 days (15TiB) (Please use this directory for all
   your testing! Do not use the work directory for tests.) (see also
   [this](https://www.dkrz.de/up/systems/mistral/hpc-concepts))
 
 Running batch jobs: Info and examples on SLURM job scheduling system at DKRZ can
 be found [here](https://www.dkrz.de/up/systems/mistral/running-job).
 
+Congratulations! Please go here [here](#GitHub-account-(Advanced)) next.
 
 ### Using your own machine
 
+Please skip this section if you are not going to use ESMValTool on your
+local machine and go [here](#gitHub-account-(advanced)).
+
 If you are planning on running ESMValTool on your own machine, please make sure
 that you are able to download CMIP data and that you have several GB of space
 available to install conda & ESMValTool, but also enough to make a copy of some
@@ -263,12 +262,13 @@ You will also need to able to use:
 
 #### Linux/Unix
 
-For Linux/Unix systems, follow the instructions of the [Installation episode]({{
+For Linux/Unix systems, please follow the instructions of the [Installation episode]({{
 page.root}}{% link _episodes/02-installation.md  %}).
 
+
 #### Mac OSx
 
-Also, for Mac OSx systems, follow the instructions of the [Installation episode]({{
+Also, for Mac OSx systems, please follow the instructions of the [Installation episode]({{
 page.root}}{% link _episodes/02-installation.md  %}).
 
 #### Windows
@@ -278,9 +278,7 @@ but successful usage has been reported through the
 [Windows Subsystem for Linux(WSL)](https://docs.microsoft.com/en-us/windows/wsl/),
 available in Windows 10.
 
-
-
-## Github account (Advanced)
+## GitHub account (Advanced)
 
 You don’t need a github account to participate in the tutorial. However, if you
 want to raise an issue, contribute to the discussions, or share your code,
@@ -292,29 +290,26 @@ github](https://lab.github.com/githubtraining/introduction-to-github).
 You may hear a few of the following phrases during the tutorial. Don’t be
 alarmed, they will make sense eventually.
 
-### github issues
+### GitHub issues
+
 Issues are github’s ticketing system. They allow users and developers to discuss
 problems, identify bugs, or to make suggestions. Each issue is assigned a number
-and will have it’s own page on github.
+and will have it’s own page on GitHub.
 
-Here’s an explanation of the [github
+Here’s an explanation of the [GitHub
 issues](https://guides.github.com/features/issues/).
 
 Raising an issue is the act of creating a new issue. If you are asked to raise
 an issue, please follow any instructions that you are given, and also make sure
 that you read the default issue text.
 
+### GitHub pull requests
 
-### pull request
-
-A github pull request is the act of requesting that a branch is merged with
-another branch.
+A GitHub pull request is the act of requesting that a branch is merged with another branch.
 
 This is an advanced feature of GitHub, and will generally be performed by the
 ESMValTool development team.
 
-
-
 ## Install conda
 
 The python package manager Conda (anaconda or miniconda) needs to be installed
@@ -324,7 +319,4 @@ central version installed already.
 More details on this process are available in the [Installation episode]({{
 page.root}}{% link _episodes/02-installation.md  %}).
 
-
-
 {% include links.md %}
-