Merge remote-tracking branch 'origin/master' into setup_md

Author: ledm

.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: Jekyll site CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-20.04
+    steps:
+    - uses: actions/checkout@v2
+    - name: Setup Ruby
+      uses: ruby/[email protected]
+      with:
+        ruby-version: 2.7
+    - name: Cache Ruby deps
+      uses: actions/cache@v2
+      with:
+        path: vendor/bundle
+        key: ruby-deps-${{ hashFiles('**/Gemfile.lock') }}
+        restore-keys: |
+          ruby-deps-
+    - name: Ruby deps
+      run: gem install json kramdown jekyll bundler
+    - name: Setup Python
+      uses: actions/setup-python@v2
+      with:
+        python-version: '3.x'
+    - name: Python deps
+      run: pip install pyyaml
+    - name: Nokogiri deps
+      run: sudo apt install -y pkg-config libxml2-dev libxslt-dev
+    - name: Site deps
+      run: bundle install
+    - name: Build site
+      run: bundle exec jekyll build
+    - name: Check all lessons
+      run: make lesson-check-all

CONTRIBUTING.md

@@ -1,68 +1,94 @@
 # Contributing to ESMValTool tutorial
 
-[ESMValTool][tutorial-site] tutorial is an open-source project in [ESMValGroup][ESMValTool-site] and we greatly value contributions of all kinds: fixes to this tutorial, bug reports, reviews of pull requests, infrastructure improvements, community help, and outreach. We value the time you invest in contributing and strive to make the process as easy as possible. If you have suggestions for improving the process of contributing, please open an [issue][issues]. To do so, click on `New issue` in the `issues` tab of this repository and choose the `Suggestion` template.
+[ESMValTool][tutorial-site] tutorial is an open-source project in
+[ESMValGroup][ESMValTool-site] and we greatly value contributions of all kinds:
+fixes to this tutorial, bug reports, reviews of pull requests, infrastructure
+improvements, community help, and outreach. We value the time you invest in
+contributing and strive to make the process as easy as possible. If you have
+suggestions for improving the process of contributing, please open an
+[issue][issues]. To do so, click on `New issue` in the `issues` tab of this
+repository and choose the `Suggestion` template.
 
 ## Acknowledgement
 
-The format of this tutorial is based on the [Software Carpentry][swc-site], which is an open-source project.
+The format of this tutorial is based on the [Software Carpentry][swc-site],
+which is an open-source project.
 
 ## Agreement
 
-By contributing, you agree that we may redistribute your work under [our license](LICENSE.md).
-In exchange, we will address your issues and/or assess your change proposal as promptly as we can, and help you become a member of our community.
-Everyone involved in this [tutorial](tutorial-repo) agrees to abide by our [code of conduct](CODE_OF_CONDUCT.md).
+By contributing, you agree that we may redistribute your work under [our
+license](LICENSE.md). In exchange, we will address your issues and/or assess
+your change proposal as promptly as we can, and help you become a member of our
+community. Everyone involved in this [tutorial](tutorial-repo) agrees to abide
+by our [code of conduct](CODE_OF_CONDUCT.md).
 
 ## How to Contribute
 
 There are many ways to contribute:
 
-* If you do not have a [GitHub][github] account,
-you can send us comments by [email][email].
-However,
-we will be able to respond more quickly when you use one of the other methods described below.
-
-* If you have a [GitHub][github] account, work in this [repository][tutorial-repo],
-which can be viewed at the tutorial [site][tutorial-site].
-You can ask your questions, report problems or suggest improvements by [creating an issue][issues].
-This is the easiest way to tell us about your ideas, and a good way to introduce yourself
-and to meet some of our community members.
-This allows us to assign the item to someone and to respond to it in a threaded discussion.
-To open an issue, click on `New issue` in the `issues` tab of this repository and choose a template from the [list](https://github.com/ESMValGroup/tutorial/issues/new/choose) as described below:
+* If you do not have a [GitHub][github] account, you can send us comments by
+  [email][email]. However, we will be able to respond more quickly when you use
+  one of the other methods described below.
+
+* If you have a [GitHub][github] account, work in this
+  [repository][tutorial-repo], which can be viewed at the tutorial
+  [site][tutorial-site]. You can ask your questions, report problems or suggest
+  improvements by [creating an issue][issues]. This is the easiest way to tell
+  us about your ideas, and a good way to introduce yourself and to meet some of
+  our community members. This allows us to assign the item to someone and to
+  respond to it in a threaded discussion. To open an issue, click on `New issue`
+  in the `issues` tab of this repository and choose a template from the
+  [list](https://github.com/ESMValGroup/tutorial/issues/new/choose) as described
+  below:
   * for asking a question, please use `Question and answer`.
   * for reporting a bug, please use `Bug reports`.
   * for developing lesson material, please use `New lesson material`.
   * for adding a feature to the repository, please use `Suggestion`.
 
-* If you would like to add what is already discussed in an issue,
-you can submit a [pull request][PR] and make use of the `pull request checklist`.
-Each pull request is reviewed at least by one reviewer who is a community volunteer.
-The [maintainers][tutorial-maintainers] have final say over what gets merged into the tutorial.
+* If you would like to add what is already discussed in an issue, you can submit
+  a [pull request][PR] and make use of the `pull request checklist`. Each pull
+  request is reviewed at least by one reviewer who is a community volunteer. The
+  [maintainers][tutorial-maintainers] have final say over what gets merged into
+  the tutorial.
 
 ## Tutorial guidelines
 
-This section demonstrates all the instructions for developing a lesson in the [ESMValTool tutorial][tutorial-site].
-The tutorial is a set of lessons (or episodes) that together teach **basic** skills needed to work with [ESMValTool][ESMValTool-doc] in climate-related domains.
+This section demonstrates all the instructions for developing a lesson in the
+[ESMValTool tutorial][tutorial-site]. The tutorial is a set of lessons (or
+episodes) that together teach **basic** skills needed to work with
+[ESMValTool][ESMValTool-doc] in climate-related domains.
 
 ### Lesson development
 
-The content of this tutorial is mainly developed based on the [Carpentries Curriculum Development Handbook][swc-handbook]. The handbook explains why we teach the way we do, and why our lessons are designed the way they are.
-If you are contributing to existing lesson materials, please make sure the content conforms to the concepts provided in the handbook.
+The content of this tutorial is mainly developed based on the [Carpentries
+Curriculum Development Handbook][swc-handbook]. The handbook explains why we
+teach the way we do, and why our lessons are designed the way they are. If you
+are contributing to existing lesson materials, please make sure the content
+conforms to the concepts provided in the handbook.
 
-We recommend using software to check spelling or grammatical errors.
-The following link will guide you through a list of tools for several editors:
+We recommend using software to check spelling or grammatical errors. The
+following link will guide you through a list of tools for several editors:
 <http://wiki.languagetool.org/software-that-supports-languagetool-as-a-plug-in-or-add-on>
 
 ### Lesson organization
 
-Each lesson is made up of episodes, which are focused on a particular topic and include time for both teaching and exercises. If you are making a new episode, please make sure the content conforms to the [Carpentries lesson organization][swc-lesson-organization].
+Each lesson is made up of episodes, which are focused on a particular topic and
+include time for both teaching and exercises. If you are making a new episode,
+please make sure the content conforms to the [Carpentries lesson
+organization][swc-lesson-organization].
 
 ### Lesson formatting
 
-Episodes are [Markdown](https://en.wikipedia.org/wiki/Markdown) files. If you are making a new episode or contributing to existing ones, please make sure the content conforms to the [Carpentries lesson formatting][swc-lesson-formatting].
+Episodes are [Markdown](https://en.wikipedia.org/wiki/Markdown) files. If you
+are making a new episode or contributing to existing ones, please make sure the
+content conforms to the [Carpentries lesson formatting][swc-lesson-formatting].
 
-We also, recommend using a linter to check errors in Markdown files.
-For example, a [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) can be installed as an extension in [Visual Studio Code](https://code.visualstudio.com/).
-Alternatively, a linter can be installed with:
+We also, recommend using a linter to check errors in Markdown files. For
+example, a
+[markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint)
+can be installed as an extension in [Visual Studio
+Code](https://code.visualstudio.com/). Alternatively, a linter can be installed
+with:
 
 ```bash
 gem install mdl
@@ -74,7 +100,10 @@ and can be used as:
 mdl your_markdown_filename
 ```
 
-We use [Codacy](https://app.codacy.com/gh/ESMValGroup/tutorial) as an automated code analysis services. To run the analyis [locally](https://github.com/codacy/codacy-analysis-cli) on Markdown files with Docker use
+We use [Codacy](https://app.codacy.com/gh/ESMValGroup/tutorial) as an automated
+code analysis services. To run the analyis
+[locally](https://github.com/codacy/codacy-analysis-cli) on Markdown files with
+Docker use
 
 ```bash
 docker run \
@@ -89,9 +118,9 @@ docker run \
 
 ### Previewing your changes locally
 
-If you are making a new episode or contributing to existing ones,
-please preview changes on your machine before submitting a [pull request][PR].
-To do so, you need to install the software described below:
+If you are making a new episode or contributing to existing ones, please preview
+changes on your machine before submitting a [pull request][PR]. To do so, you
+need to install the software described below:
 
 ```bash
 # apt (Ubuntu/Devian)
@@ -105,14 +134,15 @@ or
 sudo dnf install rubygem-bundler ruby-devel
 ```
 
-Alternatively, there is an environment file available which can be installed with:
+Alternatively, there is an environment file available which can be installed
+with:
 
 ```bash
 conda env create -f environment.yml -n esmvaltool_tutorial
 ```
 
-To install the required ruby packages, run the following command in the tutorial's
-main directory to build and serve the website locally:
+To install the required ruby packages, run the following command in the
+tutorial's main directory to build and serve the website locally:
 
 ```bash
 make serve

Makefile

@@ -132,7 +132,7 @@ lesson-check : lesson-fixme
 
 ## * lesson-check-all : validate lesson Markdown, checking line lengths and trailing whitespace
 lesson-check-all :
-	@${PYTHON} bin/lesson_check.py -s . -p ${PARSER} -r _includes/links.md -l -w --permissive
+	@${PYTHON} bin/lesson_check.py -s . -p ${PARSER} -r _includes/links.md -l -w
 
 ## * unittest         : run unit tests on checking tools
 unittest :

README.md

@@ -1,28 +1,39 @@
 # FIXME Lesson title
 
-[![Create a Slack Account with us](https://img.shields.io/badge/Create_Slack_Account-The_Carpentries-071159.svg)](https://swc-slack-invite.herokuapp.com/) [![Join the chat at https://gitter.im/ESMValGroup/Tutorial](https://badges.gitter.im/ESMValGroup/Tutorial.svg)](https://gitter.im/ESMValGroup/Tutorial?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+[![Create a Slack Account with
+us](https://img.shields.io/badge/Create_Slack_Account-The_Carpentries-071159.svg)](https://swc-slack-invite.herokuapp.com/)
+[![Join the chat at
+https://gitter.im/ESMValGroup/Tutorial](https://badges.gitter.im/ESMValGroup/Tutorial.svg)](https://gitter.im/ESMValGroup/Tutorial?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
-This repository generates the corresponding lesson website from [The Carpentries](https://carpentries.org/) repertoire of lessons. 
+This repository generates the corresponding lesson website from [The
+Carpentries](https://carpentries.org/) repertoire of lessons.
 
 ## Contributing
 
-We welcome all contributions to improve the lesson! Maintainers will do their best to help you if you have any
-questions, concerns, or experience any difficulties along the way.
+We welcome all contributions to improve the lesson! Maintainers will do their
+best to help you if you have any questions, concerns, or experience any
+difficulties along the way.
 
-We'd like to ask you to familiarize yourself with our [Contribution Guide](CONTRIBUTING.md) and have a look at
-the [more detailed guidelines][lesson-example] on proper formatting, ways to render the lesson locally, and even
-how to write new episodes. Note that the content of the web page is located in the directory [_episodes](https://github.com/ESMValGroup/tutorial/tree/master/_episodes).
+We'd like to ask you to familiarize yourself with our [Contribution
+Guide](CONTRIBUTING.md) and have a look at the [more detailed
+guidelines][lesson-example] on proper formatting, ways to render the lesson
+locally, and even how to write new episodes. Note that the content of the web
+page is located in the directory
+[_episodes](https://github.com/ESMValGroup/tutorial/tree/master/_episodes).
 
-Please see the current list of [issues][FIXME] for ideas for contributing to this
-repository. For making your contribution, we use the GitHub flow, which is
-nicely explained in the chapter [Contributing to a Project](http://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project) in Pro Git
-by Scott Chacon.
-Look for the tag ![good_first_issue](https://img.shields.io/badge/-good%20first%20issue-gold.svg). This indicates that the maintainers will welcome a pull request fixing this issue.  
+Please see the current list of [issues][FIXME] for ideas for contributing to
+this repository. For making your contribution, we use the GitHub flow, which is
+nicely explained in the chapter [Contributing to a
+Project](http://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project) in Pro
+Git by Scott Chacon. Look for the tag
+![good_first_issue](https://img.shields.io/badge/-good%20first%20issue-gold.svg).
+This indicates that the maintainers will welcome a pull request fixing this
+issue.
 
 
 ## Maintainer(s)
 
-Current maintainers of this lesson are 
+Current maintainers of this lesson are
 
 * FIXME
 * FIXME

_config.yml

@@ -2,20 +2,21 @@
 # Values for this lesson.
 #------------------------------------------------------------
 
-# Which carpentry is this ("swc", "dc", "lc", or "cp")?
+# Which carpentry is this ("swc", "dc", "lc", "cp")?
 # swc: Software Carpentry
 # dc: Data Carpentry
 # lc: Library Carpentry
 # cp: Carpentries (to use for instructor traning for instance)
-# ea: eScience Academy
-carpentry: "ea"
+# ea: eScience Academy (not implemented)
+# et: ESMValTool Tutorial (to be implemented)
+carpentry: "et"
 
 # Overall title for pages.
-title: "ESMValTool Introduction"
+title: "ESMValTool Tutorial"
 
 # Life cycle stage of the lesson
 # possible values: "pre-alpha", "alpha", "beta", "stable"
-life_cycle: "pre-alpha"
+life_cycle: "alpha"
 
 #------------------------------------------------------------
 # Generic settings (should not need to change).