This lesson is still being designed and assembled (Pre-Alpha version)

Template Lesson for DUNE

Local Setup Instructions

Overview

Teaching: 30 min
Exercises: 0 min
Questions

  • How can I set up a local server to check my lesson

Objectives

  • Learn how to set up locally

Instructions for local setup to build your lessons - very useful

Carpentries instructions

The Carpentries provide excellent instructions and examples at: https://carpentries.github.io/lesson-example/setup.html.
Carpentries has moved on to an ‘R’ based system which we are not using. We are still using this older format.

Do local setup for local rendering (optional)

Follow the instructions https://carpentries.github.io/lesson-example/setup.html#setup-for-local-rendering-of-the-lessons-optional for setup on your local machine - in principle this is optional but in practice it is really helpful. You are going to need ruby and pyYAML. I used conda on a mac but they have instructions for Windows, Mac and UNIX.

Alert

At this point you should stop following their instructions and start using our github template to avoid overwriting DUNE specific items.

Key Points

  • This is the hard part, need to get ruby

How to make a Lesson for DUNE

Overview

Teaching: 30 min
Exercises: 0 min
Questions

  • How can I make a lesson like this from scratch using the DUNE template

Objectives

  • Learn how to set up locally to build a lesson and to deploy it.

Here I describe how I built this lesson. You can follow along.

Note

Check out the previous episode to set up a local server and to do local builds.

First you need to decide on a name for your new lesson.

Note

Because github insists on using gh_pages for deployment, it is good to use your own github account for initial (and ongoing) development and pull over to /DUNE/ for the official version rather than using branches in the /DUNE/ github area.

Do local setup for local rendering (optional)

Then follow the instructions https://carpentries.github.io/lesson-example/setup.html#setup-for-local-rendering-of-the-lessons-optional for setup on your local machine - in principle this is optional but in practice it is really helpful. You are going to need ruby and pyYAML. I used conda on a mac but they have instructions for Windows, Mac and UNIX.

Alert

At this point you should stop following their instructions and start using our template to avoid overwriting DUNE specific items.

Then import this template.

GitHub Import

This is like a GitHub Fork, but is not connected to the upstream changes.

Import to your GitHub account

Please import to your own account and new lesson, work there and then move it over to /DUNE/ once you have a decent draft in place.

The difference from the carpentries is the addition of the DUNE logo and stuff specific to our lessons.

now make a local copy on the gh-pages branch and edit away

git clone -b gh-pages <your new repository>

You need to look at the following pages.

Then throw your individual modules into _episodes with leading numbers to set the order. The code will follow the ordering of the files in _episodes.

There are very nice examples and a formatting tutorial at: https://carpentries.github.io/lesson-example/

All lessons need to have a header that describes them

---
title: How to make a Lesson for DUNE
teaching: 30
exercises: 0
questions:
- How can I make a lesson like this from scratch using the DUNE template
objectives:
- Learn how to set up locally to build a lesson and to deploy it.
keypoints:
- If you can do basic markdown, you can do this. 


... body of the lesson ...

In particular, check out

You can throw supplemental stuff into _extras.

You can then build your site locally either as a server or just a local site.

local site

make site

This does a lot of setup - it’s pulling in a lot of ruby “gem” files.

Your local site will be in _sites/index.html

Checking

make lesson-check

will tell you about all the FIXME’s you haven’t fixed and missing formatting syntax.

local server

make serve

will launch a web server and a site at: http://127.0.0.1:4000

You may need to reload the web site to see your changes.

Note

These will hang around until you kill them so if you try to launch twice you can’t. Look for processes with:

ps -ef | grep 'jekyll serve'

You can identify the process number from the second column that is printed and kill that process. Alternatively this can be achieved with a one line command:

ps -ef | grep '[j]ekyll serve' | awk '{print $2}'

The awk command grabs the second column, the PID. The [j] is a trick to stop it from also passing the grep process to kill also.

Publishing your draft site to <yourname>.github.io/<yoursite>

Ok, so now you should be able to push your site to github.io

We have provided a gitadd.sh script that adds the most common source files so you don’t mistakenly publish all of the html you just generated.

# make certain you're up to date with the main repo
git pull
# make certain you are in your gh-pages branch
git status | grep gh-pages 
source gitadd.sh
git commit -m " I DID SOMETHING"
git push

Wait a couple of minutes and you should see your page appear at:

https://<yourname>.github.io/<yoursite>

Ok, once you have your site in decent shape you can import it back to

https://github.com/DUNE/<yoursite>

Making it official

Once you have it checked out you can use the import function to make an official dune site.

Maintaining your site

Key Points

  • If you can do basic markdown, you can do this.

  • Import the template to your own GitHub account when developing new lessons