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

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: 10 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

Because github insists on using ghpages for deployment, it is good to use your own github account for initial (and ongoing) development and pull over to github.com/dune for the official version rather than using branches in the github.com/dune github area. If you do not have one, set one up now at github.com.

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

What is your plan for your lesson? What are you going to call it?

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 into a new area in your account with your new name

  1. Make certain you have a personal github site
  2. Make a new repo on the github site: https://github.com/<yourname>?tab=repositories by hitting the New button and entering the new name
  3. Do the following git commands on your local machine 
     # make a copy with your new name
 git clone https://github.com/dune/lesson-template.git <yournewlessonname>
 cd <yournewlessonname>
 # tell git that it is attached to the empty repository you just set up in step 2. 
 git remote set-url origin https://github.com/<yourname>>/<yournewlessonname>.git
 # push it back to git
 git push
  4. Your code should appear at https://github.com/<yourname>/<yournewlessonname>and your page should appear at https://<yourname>.github.io/<yournewlessonname> in a couple of minutes.

if you can an error message from git

This is a pretty big repository so one can hit buffer sizes. This is an error I saw when I tried to push for the first time.

git push
Enumerating objects: 3939, done.
Counting objects: 100% (3939/3939), done.
Delta compression using up to 12 threads
Compressing objects: 100% (1390/1390), done.
error: RPC failed; HTTP 400 curl 22 The requested URL returned error: 400
send-pack: unexpected disconnect while reading sideband packet
Writing objects: 100% (3939/3939), 3.86 MiB | 9.98 MiB/s, done.
Total 3939 (delta 2476), reused 3939 (delta 2476), pack-reused 0
fatal: the remote end hung up unexpectedly

By increasing the buffer size

git config http.postBuffer 524288000

and trying again.

Or you could try using the Github importer

Note: this failed when we tried it recently so above instructions may be better

GitHub Importer (failed when we tried it)

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.

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

If you did a github import you need to get a local copy

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

Otherwise you are already there.

Explore the file structure

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 ...

There is a more information at:

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

(note that it is http not https)

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

Practice area

Overview

Teaching: 30 min
Exercises: 1 min
Questions

  • Try making various examples yourself

Objectives

  • Learn how to format different use cases

  1. Make a Note

      > ## Note check out the Markdown CheatSheet for standard syntax 
 > check out the Markdown CheatSheet for standard syntax 
 > [Cheat Sheet for Markdown](https://www.markdownguide.org/cheat-sheet/)
 {: .callout}

    Produces:

    Note check out the Markdown CheatSheet for standard syntax

    check out the Markdown CheatSheet for standard syntax Cheat Sheet for Markdown

    These tutorials use some addons. See Formatting episode for details.

    I have to indent the text within a particular numbered section or the number resets

  2. Refer to a different episode

     [Formatting episode](../04-formatting/index.html)

    Produces:

    Formatting episode

  3. Show me some source code

     for thing in collection:
     do_something

    or you can use specific language specifiers like {: .language-python}

    Please write code so that people can copy directly over to their terminal to run it. No terminal prompts at the beginning of lines.

  4. Ask me a tricky question

     > ## Challenge Title
 >
 >  What happens if I type?
 >
 > ~~~
 > rm -rf *
 > ~~~
 > {: .source}
 >
 > > ## Solution
 > >
 > > This is a bad thing to do
 > >
 > > ~~~
 > > You have deleted all your files
 > > ~~~
 > > {: .output}
 > {: .solution}
 {: .challenge}

    Produces:

    Challenge Title

    What happens if I type

    rm -rf *

    Solution

    This is a bad thing to do

    You have deleted all your files

  5. Make certain you can version things so the lesson is easy to keep up to date.

     export CODE_VERSION=v20

    Allows you to do

     setup $CODE_VERSION

    throughout your lesson.

    (Visual code and other editors also allow you to do global changes if you have to. )

Key Points

  • Using Markdown to make note/warnings/quizzes

Formatting

Overview

Teaching: 10 min
Exercises: 0 min
Questions

  • How are The Carpentries lessons formatted?

Objectives

  • Explain the header of each episode.

  • Explain the overall structure of each episode.

  • Explain why blockquotes are used to format parts of episodes.

  • Explain the use of code blocks in episodes.

this is a copy of the formatting instructions. Copy example code from this into your practice area and modify.

A lesson consists of one or more episodes, each of which has:

The diagram below shows the internal structure of a single episode file (click on the image to see a larger version):

Formatting Rules

Maximum Line Length

Limit all lines to a maximum of 100 characters. bin/lesson_check.py will report lines longer than 100 characters and this can block your contributions of being accepted.

The two reasons behind the decision to enforce a maximum line length are (1) make diff and merge easier in the command line and other user interfaces and (2) make update of translation of the lessons easier.

Locations and Names

Episode files are stored in _episodes or, for the case of R Markdown files, _episodes_rmd so that Jekyll will create a collection for them. Episodes are named dd-subject.md, where dd is a two-digit sequence number (with a leading 0) and subject is a one- or two-word identifier. For example, the first three episodes of this example lesson are _episodes/01-design.md, _episodes/02-tooling.md and _episodes/03-formatting.md. These become /01-design/index.html, /02-tooling/index.html, and /03-formatting/index.html in the published site. When referring to other episodes, use:

[link text]({{ page.root }}{% link _episodes/dd-subject.md %})

i.e., use Jekyll’s link tag and the name of the file.

Episode Header

Each episode’s YAML header must contain:

These values are stored in the header so that Jekyll will read them and make them accessible in other pages as site.episodes.the_episode.key, where the_episode is the particular episode and key is the key in the YAML header. This lets us do things like list each episode’s key questions in the syllabus on the lesson home page.

Episode Structure

The episode layout template in _layouts/episode.html automatically creates an introductory block that summarizes the lesson’s teaching time, exercise time, key questions, and objectives. It also automatically creates a closing block that lists its key points. In between, authors should use only:

Authors should not use:

Linking section IDs

In the HTML output each header of a section, code sample, exercise will be associated with an unique ID (the rules of the ID generation are given in kramdown documentation, but it is easier to look for them directly in the page sources). These IDs can be used to easily link to the section by attaching the hash (#) followed by the ID to the page’s URL (like this). For example, the instructor might copy the link to the etherpad, so that the lesson opens in learners’ web browser directly at the right spot.

Formatting Code

Inline code fragments are formatted using backticks (`). Longer code blocks are formatted by opening and closing the block with ~~~ (three tildes), with a class specifier after the block:

~~~
for thing in collection:
    do_something
~~~
{: .source}

which is rendered as:

for thing in collection:
    do_something

The class specified at the bottom using an opening curly brace and colon, the class identifier with a leading dot, and a closing curly brace. The template provides three styles for code blocks:

.source: program source.

.output: program output.

.error: error messages.

Syntax Highlighting

The following styles like .source, but include syntax highlighting for the specified language. Please use them where possible to indicate the type of source being displayed, and to make code easier to read.

.language-bash: Bash shell commands:

echo "Hello World"

.language-html: HTML source:

<html>
<body>
<em>Hello World</em>
</body>
</html>

.language-make: Makefiles:

all:
    g++ main.cpp hello.cpp -o hello

.language-matlab: MATLAB source:

disp('Hello, world!')

.language-python: Python source:

print("Hello World")

.language-r: R source:

cat("Hello World")

.language-sql: SQL source:

CREATE PROCEDURE HelloWorld AS
PRINT 'Hello, world!'
RETURN (0)

Alternative Syntax highlighting

The majority of our lessons that use styles will have the three tilde syntax, but this is a historical artifact and not commonly used outside of kramdown. You can specify a code block by using three backticks followed by the class instead of the syntax above.

```html
<html>
<body>
<em>Hello World</em>
</body>
</html>
```

<html>
<body>
<em>Hello World</em>
</body>
</html>

NOTE: this syntax will not work for error, output, or warning code blocks.

Historical Artifacts

This code block syntax with three tildes followed by an inline attribute list is a departure from the original markdown syntax. You may be wondering why Carpentries lessons used this syntax in the first place if it was so different from original markdown.

At the time this guide was originally written, Lessons in The Carpentries were using Jekyll with kramdown to render Markdown to HTML and back then, kramdown did not recognise three backticks as code blocks.

Highlighting for other languages

You may use other language-* classes to activate syntax highlighting for other languages. For example,

~~~
title: "YAML Highlighting Example"
description: "This is an example of syntax highlighting for YAML."
array_values:
    - value_1
    - value_2
~~~
{: .language-yaml }

will produce this:

title: "YAML Highlighting Example"
description: "This is an example of syntax highlighting for YAML."
array_values:
    - value_1
    - value_2

Note that using .language-* classes other than .language-bash .language-html, .language-make, .language-matlab, .language-python, .language-r, or .language-sql will currently cause one of the tests in the lesson template’s make lesson-check to fail for your lesson, but will not prevent lesson pages from building and rendering correctly.

Special Blockquotes

We use blockquotes to group headings and text rather than wrapping them in div elements. in order to avoid confusing Jekyll’s parser (which sometimes has trouble with Markdown inside HTML). Each special blockquote must begin with a level-2 header, but may contain anything after that. For example, a callout is formatted like this:

> ## Callout Title
>
> text
> text
> text
>
> ~~~
> code
> ~~~
> {: .source}
{: .callout}

(Note the empty lines within the blockquote after the title and before the code block.) This is rendered as:

Callout Title

text text text

code

The lesson template defines styles for the following special blockquotes:

.callout

An aside or other comment.

.challenge

An exercise.

.checklist

Checklists.

.discussion

Discussion questions.

.keypoints

Key points of an episode.

.objectives

Episode objectives.

.prereq

Prerequisites.

.solution

Exercise solution.

.testimonial

A laudatory quote from a user.

.caution

A warning.

Note that .challenge and .discussion have the same color but different icons. Note also that one other class, .quotation, is used to mark actual quotations (the original purpose of the blockquote element). This does not add any styling, but is used to prevent the checking tools from complaining about a missing class.

Most authors will only use .callout, .challenge, and .prereq, as the others are automatically generated by the template. Note that .prereq is meant for describing things that learners should know before starting this lesson; setup instructions do not have a particular style, but are instead put on the setup.md page.

Note also that solutions are nested inside exercises as shown below:

> ## Challenge Title
>
> This is the body of the challenge.
>
> ~~~
> it may include some code
> ~~~
> {: .source}
>
> > ## Solution
> >
> > This is the body of the solution.
> >
> > ~~~
> > it may also include some code
> > ~~~
> > {: .output}
> {: .solution}
{: .challenge}

The double indentation is annoying to edit, but the alternatives we considered and discarded are worse:

  1. Use HTML <div> elements for the challenges. Most people dislike mixing HTML and Markdown, and experience shows that it’s all too easy to confuse Jekyll’s Markdown parser.

  2. Put solutions immediately after challenges rather than inside them. This is simpler to edit, but clutters up the page and makes it harder for tools to tell which solutions belong to which exercises.

Applying a Shadow to Images

By default, images in the lesson are displayed without borders or shadows. In some circumstances, it may be desirable to make images stand out from the background of the page, for example, when using screenshots that include text on white background. You can add a drop shadow effect to images by applying the image-with-shadow class to them:

![image alt text](path/to/image/source.svg){: .image-with-shadow }

Key Points

  • Lesson episodes are stored in _episodes/dd-subject.md.

  • Each episode’s title must include a title, time estimates, motivating questions, lesson objectives, and key points.

  • Episodes should not use sub-titles or HTML layout.

  • Code blocks can have the source, regular output, or error class.

  • Special sections are formatted as blockquotes that open with a level-2 header and close with a class identifier.

  • Special sections may be callouts or challenges; other styles are used by the template itself.