carpentries/lesson-example

Example lesson using The Carpentries lesson template.

lesson-example

This repository shows how to create a lesson using The Carpentries lesson template, and is itself an example of the use of that template. Please see https://carpentries.github.io/lesson-example/ for a rendered version of this material, including detailed instructions on design, setup, and formatting.

Quick Instructions

1. Do not fork this repository directly on GitHub. Instead, please follow the instructions in the setup instructions to create a repository for your lesson by importing material from the styles repository.

2. Once you have created your repository, run bin/lesson_initialize.py to create standard lesson-specific files. You must edit several values in _config.yml so that GitHub Pages will render your lesson correctly.

3. Please read the episodes of this lesson to format your material.

4. Please keep the master copy of your lesson in your repository's gh-pages branch, since that is what is automatically published as a website by GitHub.

5. To preview material, please run make serve from the command line to launch Jekyll with the correct parameters, or push to your repository's gh-pages branch and let GitHub take care of the rendering.

6. Run make lesson-check to check that your files follow our formatting rules.

7. If you find an error or omission in this documentation, please file an issue in this repository. If you find an error or omission in the lesson template, please file an issue in the styles repository instead.

Layout

The layout of this repository is explained in this site's episodes. In brief:

1. The source for pages that appear as top-level items in the navigation bar are stored in the root directory, including the home page (index.md), the reference page (reference.md), and the setup instructions (setup.md).

2. Source files for lesson episodes are stored in _episodes; _episodes/01-xyz.md generates /01-xyz/index.html, which can be linked to using /01-xyz/.

3. If you are writing lessons in R Markdown, source files go in _episodes_rmd. You must run make lesson-rmd to turn these into Markdown in _episodes and commit those Markdown files to the repository (since GitHub won't run anything except Jekyll to format material). You must also commit any figures generated from your lessons, which are stored in the fig directory.

4. Files that appear under the "extras" menu are stored in _extras.

5. Figures are stored in the fig directory, data sets in data, source code in code, and miscellaneous files in files.

Getting Started

1. Run bin/lesson_initialize.py to create files that can't be stored in the template repository (because they would cause repeated merge conflicts), then edit _config.yml as described in the documentation.

2. Run make lesson-check at any time to check that your lesson files follow our formatting rules. If you come across formatting issues that the checker doesn't report, please file an issue in the styles repository.

3. For a list of helpful commands run make in this directory. If you are looking for things to work on, please see the list of issues for this repository.

lesson-example's Issues

CommonMark changed API

after pip-installing dependencies, make check fails with

python tools/check.py .
Traceback (most recent call last):
  File "tools/check.py", line 846, in <module>
    main(parsed_args)
  File "tools/check.py", line 831, in main
    res = validate_single(fn, template=template)
  File "tools/check.py", line 711, in validate_single
    validate_file = validator(filepath)
  File "tools/check.py", line 80, in __init__
    ast = self._parse_markdown(self.markdown)
  File "tools/check.py", line 87, in _parse_markdown
    parser = CommonMark.DocParser()
AttributeError: module 'CommonMark' has no attribute 'DocParser'
Makefile:38: recipe for target 'check' failed
make: *** [check] Error 1

This is because CommonMark 0.6 has changed its API. Pinning down the version fixes the problem

$ pip install --upgrade CommonMark==0.5.5
Collecting CommonMark==0.5.5
  Using cached CommonMark-0.5.5-py2.py3-none-any.whl
Installing collected packages: CommonMark
  Found existing installation: CommonMark 0.6.3
    Uninstalling CommonMark-0.6.3:
      Successfully uninstalled CommonMark-0.6.3
Successfully installed CommonMark-0.5.5
You are using pip version 7.1.2, however version 8.0.0 is available.
You should consider upgrading via the 'pip install --upgrade pip' command.
$ make check 
python tools/check.py .

Maybe versions could be pinned down in requirements.txt?

An example Rmd file would be useful

It's useful having the 01-introduction.md file. It would also be useful to have an example file for the Rmd. Also having that file would let the 'make lesson-rmd' command be tested.

GitHub screenshot

On #67, @timtomch uses his own user for the screenshots. Can we use @swcarpentry user for the screenshots? This will enable more people to take the screenshots and avoid to change the text each time that someone update the files based on their screenshots.

"master repository" and "master branch"

We received the report that use "master repository" is confusing when we had "master branch". Was suggested to use "official repository" or "upstream repository" instead of "master repository".

YAML typo in _episodes/04-formatting.md

In the YAML for file
https://github.com/swcarpentry/lesson-example/blob/gh-pages/_episodes/04-formatting.md

the keypoints has the following line:
"Code blocks can be have the source, regular output, or error class."

Probably "can be have" should either be "can be" or "have"

How to store instructors' notes inline

Should we store instructors' notes in the lesson episodes themselves, rather than in a separate file? If so, how should they be presented? As an icon which produces a pop-up when clicked? As an accordion section (expand/contract) in the main body of the lesson? Or...?

Add "Edit on GitHub"

Raw of proof concept screenshot

This is related with #97 and the discussion of how to increase contributions to the lessons.

In the past we used GitHub Ribbons but this was deprecated on the new style for one reason that I don't know.

cc @ErinBecker

missing image file in setup.md

In setup.md under 'Creating a lesson' point 7, there's a missing image file

Add description of publication procedure

Explain when and how we publish lessons and assign authorship/editorship credit.

Avoid "CRAN without setting a mirror"

Copy http://stackoverflow.com/a/8475208/1802726 as instruction to solve

$ make serve      
Loading required package: knitr
Loading required package: stringr
Loading required package: checkpoint

checkpoint: Part of the Reproducible R Toolkit from Microsoft
https://mran.microsoft.com/documents/rro/reproducibility/
Installing missing required packages: ggplot2
Installing package into ‘/home/raniere/R/x86_64-pc-linux-gnu-library/3.3’
(as ‘lib’ is unspecified)
Error in contrib.url(repos, type) : 
  trying to use CRAN without setting a mirror
Calls: source ... generate_md_episodes -> install.packages -> grep -> contrib.url
Execution halted
make: *** [Makefile:84: lesson-rmd] Error 1

{: .source} tags appear in setup.md

The {: .source} tags are appearing in setup.md rather than providing formatting.

Image broken in setup.md

The image under point 7 of "Creating a new lesson" displays as a broken image icon.

Check for broken links

Lesson validator should check for broken links.

Include forking how-tos?

Wasn't sure if this would be helpful, but it is indeed possible to create/import lessons via forking on GitHub and still have the website get served. If people were interested in adding instructions for this, these are the steps:

# fork git repository online
git clone <repolink.git>
git checkout gh-pages
git push origin --delete gh-pages
git push origin gh-pages  # triggers website rebuild

Should git push origin --delete gh-pages fail, change your repository's default branch to something besides gh-pages (under settings) and try again. If gh-pages is the only branch:

• create a dummy branch: git branch dummy
• push the dummy branch to GitHub: git push origin dummy
• switch the GitHub default branch to dummy
• delete gh-pages git push origin --delete gh-pages

Running `bin/lesson_initialize.py` fails

$ bin/lesson_initialize.py 
  File "bin/lesson_initialize.py", line 341
    print('Warning: {0} already exists.'.format(path), file=sys.stderr)
                                                           ^
SyntaxError: invalid syntax

Schema.org rendering of template

Can we port datacarpentry/lesson-template-ARCHIVED#27 to here?

Use submodules to easy bootstrap new lesson

@jduckles was talking with me about using Git submodules to easy bootstrap new lessons. For a example, see https://github.com/coderefinery/git-intro.

GitHub Pages supports submodule!

If your GitHub Pages site repository contains submodules, they will automatically be pulled in when the Page is built.

Benefits

You can use http://import.github.com/new to start a new repository with the correct files and GitHub online editor to write the lesson.

Limitations

To edit the submodule files you will need to

1. Fork the submodule.
2. Edit .gitmodules to point to your fork.

TODO

Investigate more limitations.

The "Contributing" link points to a Markdown file, not an HTML file

In the

Source/Contributing/Contact

trimuvirate in the footer of the pages, I realised, because I was viewing
some pages offline, that it referred to

file:///blob/gh-pages/CONTRIBUTING.md

so a dot-MD file inside the GitHub repo and not an HTML page,
created within the _sites directory, even though the distribution
contains a CONTRIBUTING.md in the top-level directory which
is alongside a LICENSE.md that does get turned into an HTML
page.

When one is viewing online, the link to the lesson's repository's blob
of the MD-file will automatically get presented as an HTML page but,
given the existence of the CONTRIBUTING.md in the top-level
directory, I thought to ask if it was the intention point to the blob, and
not an HTML file that could be created?

Provide anchors for definition list items in glossary

May require enhancing Jekyll.

typo in _episodes_rmd/06-rmarkdown-example.Rmd

https://github.com/swcarpentry/lesson-example/blob/gh-pages/_episodes_rmd/06-rmarkdown-example.Rmd
After the figure there is the line:

"For the challenges and their solutions, you need to pay attention to the where the > go"

One of the "the"s needs to go (the first).

Also, would be good to but back quotes around >, as in >

Repo README needs a link to github.io

https://swcarpentry.github.io/lesson-example/

Mention that the example depends on R

To avoid:

$ make serve                     
Loading required package: knitr
Loading required package: stringr
Loading required package: checkpoint
Error in generate_md_episodes() : 
  The checkpoint package is required to build the lessons.
Calls: source ... withVisible -> eval -> eval -> generate_md_episodes
In addition: Warning message:
In library(package, lib.loc = lib.loc, character.only = TRUE, logical.return = TRUE,  :
  there is no package called ‘checkpoint’
Execution halted
make: *** [Makefile:84: lesson-rmd] Error 1

Probably include instructions to install the R packages.

Update copyright year

The lesson websites still say (c) 2016. Unless this is intended, can the year be updated automatically? Alternatively, there should maybe be a range - 20XX - 2017 with XX the first year the lesson was available.

Same issue applies to the training template https://github.com/swcarpentry/training-template.

Document the standard labels for issues and pull requests.

Following instructions leads you between lesson-template and lesson-example, where is the README?

The github importer link gets you the lesson-template repo. Then, step 10, sends you over here, where you are informed that you should have README file in your repo, but at this point, you don't have a README file, because lesson-template doesn't have that. At which point you start questioning yourself: have I misunderstood these instructions?

Make challenges appear open by default

With the challenges being click to open, there has been some confusion about where the challenges are until people realize they need to click on the arrow.

In the Data Carpentry lessons and now in the instructor training lessons, the behavior of the challenges has been changed, so that the default is that they are open rather than closed. Should that be the default behavior in the template?

This is modified is assets/js/lesson.js

Add note to FAQ explaining that SVG display doesn't work in GitHub preview

See discussion in swcarpentry/python-novice-inflammation#107

Writing R markdown lessons: challenges and callouts

Knitr code chunks do not work in the challenge, callout, or any other "blockquote" sections.

In the latest R novice gapminder lessons (swcarpentry/r-novice-gapminder#24), I've written these chunks using the standard markdown code and {.output} blocks.

What are the rest of the R community doing? If this is reasonable, LAYOUT.md needs to be updated to include these instructions.

Close the open (but fully complete) 5.4 milestone

https://github.com/swcarpentry/lesson-example/milestone/2

You can close it from https://github.com/swcarpentry/lesson-example/milestone/2/edit or from https://github.com/swcarpentry/lesson-example/milestones.

Callout icon legend

@ChristinaLK wrote

Suggestion: create a default page somewhere in the template that describes what each icon in the callout boxes stands for.

From instructor training issue carpentries/instructor-training#292.

at carpentries/styles#140.

non-fast-forward error message when doing first commit

After cloning the imported version, running lesson_initialize.py and editing an _episodes file, when you go to push, you get a 'non-fast-forward' git error message

"
git push origin gh-pages
To https://github.com/tracykteal/lesson-lesson
! [rejected] gh-pages -> gh-pages (non-fast-forward)
error: failed to push some refs to 'https://github.com/tracykteal/lesson-lesson'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Integrate the remote changes (e.g.
hint: 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.
"

It's fixable with a

• git fetch origin
• git merge origin gh-pages
• git pull origin gh-pages

but it would be nice to avoid the error

step 3 of Ten Things misspelled: inititialize (extra it)

See
3. Run bin/lesson_inititialize.py once in a new lesson repository to set up standard files.

Add solution check to make lesson-check-all

@gvwilson Do you have this on your tree?

Citations

This is a comment for just about every lesson in the carpentry course and comes from a librarian, but where are the citations?

Ex:. The Bourne Again SHell reference could be cited with
C Programming by Al Stevens, Dr. Dobb's Journal, July 1, 2001

"The Mother of All Demos" could be cited as
B. (2007, August 05). Douglas Engelbart : The Mother of All Demos (2/9). Retrieved from https://www.youtube.com/watch?v=a11JDLBXtPQ

Especially since we are placing a CCL on this content it is important that copyrighted content is properly identified.

Should lessons exercises require solutions?

When a person creates a lesson exercise, they should presumably know the correct answer to the exercise. I've noticed that some exercises have solutions (the first few episodes of the unix lesson for example), but the vast majority do not. Is there a reason to not include the solutions?

I find it useful for both learners and instructors: learners will want to see solutions if they go through an episode that was not taught in their workshop, and instructors will benefit from having confirmation that their idea of the correct answer is indeed correct.

Should challenges be at the end or throughout a lesson?

There is interest in putting some challenges throughout the lessons, so that they are in the location where the instructors will be using them as they go.

swcarpentry/shell-novice#552

The original idea of having the challenges at the end is that each module is on one topic, so therefore the related challenges can all be at the end. The modules now have multiple topics in one, so it might be good to put the challenges associated with that topic in that section, rather than having them all at the end.

This could make this clearer for instructors. It could potentially be clearer for learners, self-guided or during the workshop, but we don't have much data on how self-guided learners are using the lessons.

To make this change, we would have to

• identify which challenges go in which sections
• move those challenges to those sections
• there could still be a set of 'bonus' challenges at the end that either are additional on a particular topic or are additional ones that encompass material from the whole lesson

Style guide for 'key points'

This template has a 'key points' section. As pointed out in this issue datacarpentry/sql-ecology-lesson#129 it would be good to have some sort of guidelines or style guide for the 'key points', so we know what level of detail to include and how they should be stated.

Thanks @bsmith89 @ashander for bringing this up.

Included file '_includes/all_figures.html' not found

$ make site    
jekyll build --config _config.yml,_config_dev.yml
Configuration file: _config.yml
Configuration file: _config_dev.yml
            Source: /home/raniere/software-carpentry/lesson-example
       Destination: /home/raniere/software-carpentry/lesson-example/_site
 Incremental build: disabled. Enable with --incremental
      Generating... 
  Liquid Exception: Included file '_includes/all_figures.html' not found in /home/raniere/software-carpentry/lesson-example/_extras/figures.md
jekyll 3.1.2 | Error:  Included file '_includes/all_figures.html' not found
Makefile:23: recipe for target 'site' failed
make: *** [site] Error 1

Make setup instructions more visible

Can we add a link to setup on the begin of the Schedule? Is difficult to remember that the setup instructions are on the top nav bar.

When to use backticks

We should answer @gcapes's question, swcarpentry/shell-novice#522 (comment), on the example that at the moment is our style guide.

Maintenance of Windows installer

This isn't quite the right place for this issue, but as it relates to installation and setup instructions, I wanted to put it here.

The Windows installer (https://github.com/swcarpentry/windows-installer) has degraded to the point where it's not working. The installer is crucial to the success of SWC workshops, as initial installation challenges are frustrating for learners and instructors, and if installation is not successful, then learners don't have a chance to participate in the workshop.

We need to find someone who regularly uses Windows actively to help fix this ASAP.

Finding the data for the lesson

Feedback from a recent discussion session was that they had trouble finding the data to use for the lesson. They didn't expect to find it in 'Setup' since that traditionally had been used for installation instructions.

Could there be a 'Data' tab, or maybe even better, a link to the data on the front page?

Place for helpful links?

Should references include a list of links? I have some in instructor's guide, but given the restructuring it should maybe move.

"Creating lesson" presentation refers to deprecated motivation.md

I've discovered that this slide still refers to motivation.md which seems to be deprecated as a result of PR #10.

I can't find the source for the "Creating lesson" presentation, so decided to report it in the place where motivation.md existed before.

Item 12 link to 'episodes of the lesson' is 404ing

Challenge with numbered list and code blocks doesn't number correctly

In a challenge block with a numbered list of challenges the numbering restarts after a code block. Can work around by using a bulleted list instead. LibraryCarpentry/library-python#8

02-tooling refers to "last episode" when meaning "next episode"

Just noticed that the last sentence in the Collections section of the 02-tooling episode
says

The last episode describes these files.

where the link under the "The last episode" points to the 03-organisation page, where
those files are indeed decribed, however, that's not the "last episode", according to
the Schedule, as 08-maintenance is - unless the Coffee Break is an episode in itself ?

But anyroad, I'm thinking that that should read "The next episode" ?

Pandoc

Clarify which pandoc version the makefile depends on:

pandoc 1.12 or newer

in order to run the filter programmes.

Great template though!

Small typo on the licence page

Currently reads

“Software Carpentry” an “Data Carpentry” and their respective logos are ...

so the first and`` is missing a d```

Clarify where to find instructions on formatting, building, and submitting lessons

This is coming from an issue in git-novice that should be here. See the discussion there.