diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 0000000..2ee9d0e --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1,2 @@ +github: [carpentries, swcarpentry, datacarpentry, librarycarpentry] +custom: ["https://carpentries.wedid.it"] diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md index ec2d4fe..077de4c 100644 --- a/.github/ISSUE_TEMPLATE.md +++ b/.github/ISSUE_TEMPLATE.md @@ -1,11 +1,21 @@ -Please delete this line and the text below before submitting your contribution. +
+Instructions ---- +Thanks for contributing! :heart: -Thanks for contributing! If this contribution is for instructor training, please send an email to checkout@carpentries.org with a link to this contribution so we can record your progress. You’ve completed your contribution step for instructor checkout just by submitting this contribution. +If this contribution is for instructor training, please email the link to this contribution to +checkout@carpentries.org so we can record your progress. You've completed your contribution +step for instructor checkout by submitting this contribution! If this issue is about a specific episode within a lesson, please provide its link or filename. -Please keep in mind that lesson maintainers are volunteers and it may be some time before they can respond to your contribution. Although not all contributions can be incorporated into the lesson materials, we appreciate your time and effort to improve the curriculum. If you have any questions about the lesson maintenance process or would like to volunteer your time as a contribution reviewer, please contact The Carpentries Team at team@carpentries.org. +Keep in mind that **lesson maintainers are volunteers** and it may take them some time to +respond to your contribution. Although not all contributions can be incorporated into the lesson +materials, we appreciate your time and effort to improve the curriculum. If you have any questions +about the lesson maintenance process or would like to volunteer your time as a contribution +reviewer, please contact The Carpentries Team at team@carpentries.org. ---- +You may delete these instructions from your comment. + +\- The Carpentries +
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index d9eb8c5..07aadca 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,9 +1,19 @@ -Please delete this line and the text below before submitting your contribution. +
+Instructions ---- +Thanks for contributing! :heart: -Thanks for contributing! If this contribution is for instructor training, please send an email to checkout@carpentries.org with a link to this contribution so we can record your progress. You’ve completed your contribution step for instructor checkout just by submitting this contribution. +If this contribution is for instructor training, please email the link to this contribution to +checkout@carpentries.org so we can record your progress. You've completed your contribution +step for instructor checkout by submitting this contribution! -Please keep in mind that lesson maintainers are volunteers and it may be some time before they can respond to your contribution. Although not all contributions can be incorporated into the lesson materials, we appreciate your time and effort to improve the curriculum. If you have any questions about the lesson maintenance process or would like to volunteer your time as a contribution reviewer, please contact The Carpentries Team at team@carpentries.org. +Keep in mind that **lesson maintainers are volunteers** and it may take them some time to +respond to your contribution. Although not all contributions can be incorporated into the lesson +materials, we appreciate your time and effort to improve the curriculum. If you have any questions +about the lesson maintenance process or would like to volunteer your time as a contribution +reviewer, please contact The Carpentries Team at team@carpentries.org. ---- +You may delete these instructions from your comment. + +\- The Carpentries +
diff --git a/.gitignore b/.gitignore index 1af8c2c..553849b 100644 --- a/.gitignore +++ b/.gitignore @@ -9,5 +9,11 @@ _site .Rproj.user .Rhistory .RData +.bundle/ +.vendor/ +vendor/ +.docker-vendor/ +Gemfile.lock +.*history .vscode/ -data/ +data/ \ No newline at end of file diff --git a/Gemfile b/Gemfile new file mode 100644 index 0000000..fb25ae4 --- /dev/null +++ b/Gemfile @@ -0,0 +1,10 @@ +# frozen_string_literal: true + +source 'https://rubygems.org' + +git_source(:github) {|repo_name| "https://github.com/#{repo_name}" } + +# Synchronize with https://pages.github.com/versions +ruby '>=2.5.8' + +gem 'github-pages', group: :jekyll_plugins diff --git a/Makefile b/Makefile index d291abe..b585662 100644 --- a/Makefile +++ b/Makefile @@ -3,37 +3,67 @@ # Settings MAKEFILES=Makefile $(wildcard *.mk) -JEKYLL=jekyll -JEKYLL_VERSION=3.8.5 +JEKYLL=bundle config --local set path .vendor/bundle && bundle install && bundle update && bundle exec jekyll PARSER=bin/markdown_ast.rb DST=_site +# Check Python 3 is installed and determine if it's called via python3 or python +# (https://stackoverflow.com/a/4933395) +PYTHON3_EXE := $(shell which python3 2>/dev/null) +ifneq (, $(PYTHON3_EXE)) + ifeq (,$(findstring Microsoft/WindowsApps/python3,$(subst \,/,$(PYTHON3_EXE)))) + PYTHON := python3 + endif +endif + +ifeq (,$(PYTHON)) + PYTHON_EXE := $(shell which python 2>/dev/null) + ifneq (, $(PYTHON_EXE)) + PYTHON_VERSION_FULL := $(wordlist 2,4,$(subst ., ,$(shell python --version 2>&1))) + PYTHON_VERSION_MAJOR := $(word 1,${PYTHON_VERSION_FULL}) + ifneq (3, ${PYTHON_VERSION_MAJOR}) + $(error "Your system does not appear to have Python 3 installed.") + endif + PYTHON := python + else + $(error "Your system does not appear to have any Python installed.") + endif +endif + + # Controls .PHONY : commands clean files -.NOTPARALLEL: -all : commands -## commands : show all commands. -commands : - @grep -h -E '^##' ${MAKEFILES} | sed -e 's/## //g' +# Default target +.DEFAULT_GOAL := commands -## docker-serve : use docker to build the site -docker-serve : - docker run --rm -it -v ${PWD}:/srv/jekyll -p 127.0.0.1:4000:4000 jekyll/jekyll:${JEKYLL_VERSION} make serve +## I. Commands for both workshop and lesson websites +## ================================================= -## serve : run a local server. +## * serve : render website and run a local server serve : lesson-md ${JEKYLL} serve -## site : build files but do not run a server. +## * site : build website but do not run a server site : lesson-md ${JEKYLL} build -# repo-check : check repository settings. +## * docker-serve : use Docker to serve the site +docker-serve : + docker pull carpentries/lesson-docker:latest + docker run --rm -it \ + -v $${PWD}:/home/rstudio \ + -p 4000:4000 \ + -p 8787:8787 \ + -e USERID=$$(id -u) \ + -e GROUPID=$$(id -g) \ + carpentries/lesson-docker:latest + +## * repo-check : check repository settings repo-check : - @bin/repo_check.py -s . + @${PYTHON} bin/repo_check.py -s . -## clean : clean up junk files. +## * clean : clean up junk files clean : @rm -rf ${DST} @rm -rf .sass-cache @@ -42,22 +72,26 @@ clean : @find . -name '*~' -exec rm {} \; @find . -name '*.pyc' -exec rm {} \; -## clean-rmd : clean intermediate R files (that need to be committed to the repo). +## * clean-rmd : clean intermediate R files (that need to be committed to the repo) clean-rmd : @rm -rf ${RMD_DST} @rm -rf fig/rmd-* -## ---------------------------------------- -## Commands specific to workshop websites. + +## +## II. Commands specific to workshop websites +## ================================================= .PHONY : workshop-check -## workshop-check : check workshop homepage. +## * workshop-check : check workshop homepage workshop-check : - @bin/workshop_check.py . + @${PYTHON} bin/workshop_check.py . -## ---------------------------------------- -## Commands specific to lesson websites. + +## +## III. Commands specific to lesson websites +## ================================================= .PHONY : lesson-check lesson-md lesson-files lesson-fixme @@ -85,37 +119,39 @@ HTML_DST = \ $(patsubst _extras/%.md,${DST}/%/index.html,$(sort $(wildcard _extras/*.md))) \ ${DST}/license/index.html -## lesson-md : convert Rmarkdown files to markdown +## * lesson-md : convert Rmarkdown files to markdown lesson-md : ${RMD_DST} _episodes/%.md: _episodes_rmd/%.Rmd @bin/knit_lessons.sh $< $@ -## lesson-check : validate lesson Markdown. +## * lesson-check : validate lesson Markdown lesson-check : lesson-fixme - @bin/lesson_check.py -s . -p ${PARSER} -r _includes/links.md + @${PYTHON} bin/lesson_check.py -s . -p ${PARSER} -r _includes/links.md -## lesson-check-all : validate lesson Markdown, checking line lengths and trailing whitespace. +## * lesson-check-all : validate lesson Markdown, checking line lengths and trailing whitespace lesson-check-all : - @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 --permissive -## unittest : run unit tests on checking tools. +## * unittest : run unit tests on checking tools unittest : - @bin/test_lesson_check.py + @${PYTHON} bin/test_lesson_check.py -## lesson-files : show expected names of generated files for debugging. +## * lesson-files : show expected names of generated files for debugging lesson-files : @echo 'RMD_SRC:' ${RMD_SRC} @echo 'RMD_DST:' ${RMD_DST} @echo 'MARKDOWN_SRC:' ${MARKDOWN_SRC} @echo 'HTML_DST:' ${HTML_DST} -## lesson-fixme : show FIXME markers embedded in source files. +## * lesson-fixme : show FIXME markers embedded in source files lesson-fixme : - @fgrep -i -n FIXME ${MARKDOWN_SRC} || true + @grep --fixed-strings --word-regexp --line-number --no-messages FIXME ${MARKDOWN_SRC} || true -#------------------------------------------------------------------------------- -# Include extra commands if available. -#------------------------------------------------------------------------------- +## +## IV. Auxililary (plumbing) commands +## ================================================= --include commands.mk +## * commands : show all commands. +commands : + @sed -n -e '/^##/s|^##[[:space:]]*||p' $(MAKEFILE_LIST) diff --git a/_includes/aio-script.md b/_includes/aio-script.md index a81fbcd..d90e6d6 100644 --- a/_includes/aio-script.md +++ b/_includes/aio-script.md @@ -6,45 +6,20 @@ open an issue: https://github.com/carpentries/styles/issues/new {% include manual_episode_order.html %} - +{% for lesson_episode in lesson_episodes %} -{% comment %} Create an anchor for every episode. {% endcomment %} +{% if site.episode_order %} + {% assign e = site.episodes | where: "slug", lesson_episode | first %} +{% else %} + {% assign e = lesson_episode %} +{% endif %} -{% for lesson_episode in lesson_episodes %} - {% if site.episode_order %} - {% assign episode = site.episodes | where: "slug", lesson_episode | first %} - {% else %} - {% assign episode = lesson_episode %} - {% endif %} -
+

{{ e.title }}

+ +{% include episode_overview.html teaching_time=e.teaching exercise_time=e.exercises episode_questions=e.questions episode_objectives=e.objectives %} + +{{ e.content }} + +{% include episode_keypoints.html episode_keypoints=e.keypoints %} +
{% endfor %} diff --git a/_includes/episode_keypoints.html b/_includes/episode_keypoints.html index 2baa53e..5c283ea 100644 --- a/_includes/episode_keypoints.html +++ b/_includes/episode_keypoints.html @@ -1,10 +1,17 @@ {% comment %} Display key points for an episode. {% endcomment %} + +{% if page.keypoints == nil %} +{% assign episode_keypoints = include.episode_keypoints %} +{% else %} +{% assign episode_keypoints = page.keypoints %} +{% endif %} +

Key Points

diff --git a/_includes/episode_overview.html b/_includes/episode_overview.html index cb87e0f..169ab26 100644 --- a/_includes/episode_overview.html +++ b/_includes/episode_overview.html @@ -1,19 +1,59 @@ {% comment %} - Display an episode's timings and learning objectives. + Display episode's timings and learning objectives. + + Regarding the `if page.*** == nil` below: + all-in-one page combines all episodes into one. + It, therefore, does not define its own objectives, exercises, + and questions, which 'normal' episodes define in the front matter. + + To display episodes' teaching and exercise times, as well as episode + questions and objectives, we pass them as parameters to the Liquid's + `include` statement when we generate the page: + + include episode_overview.html teaching_time=e.teaching ... + + Here we obtain the information we need either from the episode itself or + from the parameters passed in. {% endcomment %} + +{% if page.teaching == nil %} +{% assign teaching_time = include.teaching_time %} +{% else %} +{% assign teaching_time = page.teaching %} +{% endif %} + +{% if page.exercises == nil %} +{% assign exercise_time = include.exercise_time %} +{% else %} +{% assign exercise_time = page.exercises %} +{% endif %} + +{% if page.questions == nil %} +{% assign episode_questions = include.episode_questions %} +{% else %} +{% assign episode_questions = page.questions %} +{% endif %} + +{% if page.objectives == nil %} +{% assign episode_objectives = include.episode_objectives %} +{% else %} +{% assign episode_objectives = page.objectives %} +{% endif %} + +

Overview

- Teaching: {{ page.teaching }} min + Teaching: {{ teaching_time }} min
- Exercises: {{ page.exercises }} min + Exercises: {{ exercise_time }} min
Questions
    - {% for question in page.questions %} + {% for question in episode_questions %}
  • {{ question|markdownify }}
    • {% endfor %}
@@ -26,7 +66,7 @@

Overview

Objectives
    - {% for objective in page.objectives %} + {% for objective in episode_objectives %}
  • {{ objective|markdownify }}
    • {% endfor %}
diff --git a/_includes/lesson_footer.html b/_includes/lesson_footer.html index 03091a7..b0eb299 100644 --- a/_includes/lesson_footer.html +++ b/_includes/lesson_footer.html @@ -6,7 +6,7 @@