SIH Training Course Template

This template was last edited on 15.12.18

This repo is a skeleton or template of SIH's Carpentries-based training course lesson and workshop landing page websites. Use this when creating or running a new training course for SIH.

Step 0: What do you want?

Identify whether you want:

• to run a workshop and tell people where to go and what software to install beforehand
• to develop some new lesson materials
• to create a landing page for a series of courses, linking together multiple courses

All three of these types of websites can be made using this repository:

• workshop is probably the one you'll use most frequently, and allows you to create an event landing page. It is designed to promote an actual instance or set of trainings covering one of our lessons, for example the GIS workshop in December 2018.
• lesson creates a series of pages which can be used to develop course materials, for example Intro to Artemis. These course materials will be reused and updated for multiple deliveries throughout the year(s).
• series is used as a landing/contents page for a group of lessons that form a theme, for example the Artemis series.

Write down which of the three you want: workshop, lesson, or series.

[comment]: <All updates to course content can be made in the lesson repository, across multiple years and runnings of the course. Releases can be generated to snapshot specific versions of the lesson materials delivered on a specific day, meaning students can always access both the latest versions of the materials, and the historic one that was delivered when they came to the workshop. From a course developer perspective, we have a full history of all changes to the materials in one place.> [comment]: <Being able to create both types of websites from one repository means we can keep things consistent between teams/courses, only having to edit in one place, AND if course materials are not to be made available publicly, you can still have a workshop landing page with setup instructions, survey links and a pretty schedule.>

All of these can be set up using the GitHub interface directly (by editing the files described below), or by downloading the entire project to your local machine and editing and previewing there.

Any website created from this repository will be rendered at https://sydney-informatics-hub.github.io/yourreponame.

Step 1: Get this template

Make a copy of this training-template repository, which you will then edit to create your training course.

You can carry out this step on GitHub directly (Option 1), or by downloading this repository to your local machine (Option 2).

Option 1: Use GitHub's importer to copy this training-template repository.

1. Log in to the public GitHub. (If you do not have an account, you can quickly create one for free.) You must be logged in for the remaining steps to work.

2. Go to GitHub's importer.

3. Paste the url of this repo as the old repository to clone: https://github.com/Sydney-Informatics-Hub/training-template.

4. Select the owner for your new repository. This will be Sydney-Informatics-Hub.

5. Choose a name for your website repository:

   • If you are creating a workshop website, this name should have the form YYYY-MM-DD-\, where YYYY-MM-DD is the start date of the workshop, and workshopID is a human readable label for others to understand which workshop this could be referring to. For example, 2018-11-28-bmcR or 2018-12-12-IntroArtemis.
   • If you are creating a lesson website, the name should have the form: lesson-\-\, for example lesson-bmc-introR.
   • If you are creating a series website, the name should have the form: training-\, for example training-artemis.

6. Make sure the repository is public.

7. At this point, you should have a page like this:

You can now click Begin Import. When the process is done, you will receive a message like "Importing complete! Your new repository "Sydney-Informatics-Hub/2018-12-10-bmcR" is ready." and you can go to the new repository by clicking on the name. Proceed to Step 2 below.

Option 2: Command line local option

i. Copy this template

Make a new directory where you want to keep your local copy of the course repo, and initialise it as a git repository. See step 5

mkdir /training-course-name
cd !$ && git init

Now add the template repository as a remote, calling it template

git remote add template https://github.com/Sydney-Informatics-Hub/training-template.git

Finally, fetch and checkout the template

git fetch template gh-pages
git checkout -b gh-pages template/gh-pages

You will now have a skeleton of the course website, ready for editing. The template repo will be available as a remote repository, should you wish to update the template files later on.

ii. Create a course repo on Sydney-Informatics-Hub

Go to the Sydney Informatics Hub external git site (this site!), and create a new repository

Make sure Sydney-Informatics-Hub and not your personal account is the owner. See above to figure out what the correct name for your repository should be (something like lesson-artemis-introhpc for a lesson, and 2019-01-20-introhpc for a workshop).

Keep the repo public and do not include a README.

Once the repo has been created on Sydney-Informatics-Hub, return to your local clone of the template and execute these commands to add this new GitHub repo as a remote, and then push -u to it

git remote add origin https://github.com/Sydney-Informatics-Hub/yourreponame.git
git push -u origin gh-pages

Finally, add the Training Team to the repo, so that all members will be able to edit it. Go to the Settings tab at top right of the repo page on GitHub.com, and select Collaborators & teams from the nav menu on the left. Then select Add a team:

Step 2: Making the website

i. Editing the template

a. Settings

Before you being to edit content, there are a number of settings you need to change first:

1. In the file _config.yml

   • Set a port for your local rendering of your website (if using, see below). You may be developing multiple lessons at the same time, and if you'd like to render more than one at once, then you should assigning them different port numbers. When jekyll renders your website, it will display in your web-browser at the address localhost:<port>. Leave as is if you're working on this in GitHub.
   • If this is an SIH-developed lesson or workshop, set carpentry to be "si"; if it's a partnership one select "sp". If you do not wish to use the SIH branding, but want to keep a Carpentries brand for a course or workshop, then set the carpentry variable to "swc", "dc", "lc", or "cp" as appropriate.
   • Edit the title and series_name of your course. If it is a one-off course not part of a series, then simply set this to "Home".
   • Set the kind of course to workshop or lesson or series
   • If the course is part of a series, then set the series_home address to link to the series' page. Eg https://sydney-informatics-hub.github.io/training.artemis/ is the address of the Artemis series (Using the new naming standard, though, it should be https://sydney-informatics-hub.github.io/training-artemis/).
   • Set "yes" in the SETUP section for each of the tools that students will need to have on their machines prior to the workshop, and "no" if they don't need a particular tool. If you need a different tool(s), ask Darya or follow the instructions here FIXME to add it to the template.

2. The template includes a setup.md file that explains how to prepare your computer to connect to Artemis HPC, the Uni's compute cluster. You may need this information for your lesson; if not, adapt as required. FIXME - this REALLY NEEDS TO BE FIXED

3. The index.md file is the homepage of your course.

   • If this project is a lesson then a syllabus table will be automatically generated for you, containing the episodes in the lesson and an expected timeline.

b. (Option 1) Making a new workshop site

These lines are essential. At minimum, any pages you want rendered will need to begin with two lines of ---; the lines enclosed by these triple-dashes are YAML variable declarations.

Make sure to estimate the time you expect the lesson components will take. This will automatically be displayed on the landing page of your lesson.

Figures may be kept in the fig subfolder. There are other folders for various content as well.

b. (Option 3) Making a new series

The default website generated from this repository is set to be a workshop, so if you want to make a series website instead, you'll need to rename some files. First,

1. Rename index.md to hidden file .workshop_index.md and rename hidden file .lesson_index.md to index.md (no, this is not a typo: the lesson file is used to make both lesson and series pages)

2. Edit the contents of this index.md file, as it will be the landing page for your series.

• Replace the Follow-on courses paragraph with an table listing each course and it's description, eg (in Markdown code)

  | Lesson  | Overview |
  | ------- | ---------- |
  | [Course 1]({{ site.sih_pages }}/lesson-<series>-<course1>) | Description 1 |
  | [Course 2]({{ site.sih_pages }}/lesson-<series>-<course2>) | Description 2 |

If you were working directly on GitHub, you are done! You can now get a coffee and wait 5-15 minutes for the website to render on GitHub pages, and then come back to fix/debug.

ii. (Optional) Setting up Jekyll to render your lesson website locally

You will want to set up Jekyll so that you can preview changes on your own machine before pushing them to GitHub. To do this you must install the software described below. (Julian Thilo's instructions for installing Jekyll on Windows.)

1. Ruby. This is included with Linux and macOS; the simplest option on Windows is to use RubyInstaller. Make sure Ruby is upto date otherwise jekyll may fail. You can test your installation by running ruby --version. For more information, see the Ruby installation guidelines.

2. RubyGems (the package manager for Ruby). You can test your installation by running gem --version.

3. Jekyll. You can install this by running gem install jekyll. On macOS, a user does not have a permission to write to /Library/Ruby/Gems/. Run gem install jekyll --user-install instead.

4. R Packages. We use knitr, stringr, and checkpoint to format lessons written in R Markdown, so you will need to install these to build R lessons (and this example lesson). The best way to install these packages is to open an R terminal and type:

   > install.packages('knitr', repos = 'https://', dependencies = TRUE)
   > install.packages('stringr', repos = 'https://cran.rstudio.com', dependencies = TRUE)
   > install.packages('checkpoint', repos = 'https://cran.rstudio.com', dependencies = TRUE)
   > install.packages('ggplot2', repos = 'https://cran.rstudio.com', dependencies = TRUE)

Once all of these are installed, you will probably need to run

bundle install

to ensure all required Ruby Gems are installed. Perhaps add a bundle update too for good measure!

iii. (Optional) Checking that your site conforms to the Carpentries style

The Carpentries template comes with some checking scripts.

Running make lesson-fixme will list all instances of the phrase FIXME remianing in your code base.

Running make lesson-check will do the above, and report on various different departures from the Carpentries style, or possible errors

• The following errors can be ignored:

  Missing required file ./_extras/discuss.md
  Missing required file ./_extras/guide.md
  ./_config.yml: configuration carpentry value sih is not in ('swc', 'dc', 'lc', 'cp')

  If you want to include the discussion or guide pages, then unhide them (remove the . from the front of their filenames) in the _extras folder and add the content you desire.

• The following style warnings may also be ignored

  • Unknown or missing blockquote type None occurs when you use a > block quote environment that is not one of the special types in the Carpentries style

iv. Updating the template (Optional but very welcome)

This template may be updated from time to time. If you ever wish or need to incorporate such updates into your customised course websites, you do so by pulling in the changes from the template repo into your course repo.

You will need to pay careful attention to the merge process to ensure that none of your content is overwritten by the update. You will probably want to have a graphical Git-enabled editor or diff tool to let you easily see and approve/reject any merge conflicts.

If you created your course repo from the template originally, as in these instructions, then the changes you have made should take precedence, and there should be few problems.

However, new content may be added to the template -- such additions will always include the phrase "FIXME", so make sure to search for these in your repo. (Running make lesson-fixme in your repo directory will find any remaining "FIXME"s in your files).

At your local copy

git pull template gh-pages

Contributing

We welcome all contributions to improve our courses, and to create new ones. Maintainers will do their best to help if you have any questions, concerns, or experience any difficulties along the way.

We'd like to ask you to familiarise yourself with our Contribution Guide and have a look at The Carpentries' detailed guidelines before jumping in.

This document will attempt to outline the process for creating or substantially editing a training course website.

If you simply wish to make small edits or suggestions to an existing course, this is not the repo you're looking for! To do that, please add an issue under the corresponding lesson's material.

Maintainer(s)

• Darya Vanichkina
• Hayim Dar
• Nathaniel Butterworth
• Tracy Chew

Contact sih.training@sydney.edu.au.