diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 00000000..1d7d564d --- /dev/null +++ b/.editorconfig @@ -0,0 +1,25 @@ +root = true + +[*] +charset = utf-8 +insert_final_newline = true +trim_trailing_whitespace = true + +[*.md] +indent_size = 2 +indent_style = space +max_line_length = 100 # Please keep this in sync with bin/lesson_check.py! + +[*.r] +max_line_length = 80 + +[*.py] +indent_size = 4 +indent_style = space +max_line_length = 79 + +[*.sh] +end_of_line = lf + +[Makefile] +indent_style = tab diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 00000000..2ee9d0ee --- /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 6cc9e527..077de4cf 100644 --- a/.github/ISSUE_TEMPLATE.md +++ b/.github/ISSUE_TEMPLATE.md @@ -1,9 +1,21 @@ -Please delete 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 Kate Hertweck (k8hertweck@gmail.com). +If this issue is about a specific episode within a lesson, please provide its link or filename. ---- +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 6cc9e527..07aadca2 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,9 +1,19 @@ -Please delete 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 Kate Hertweck (k8hertweck@gmail.com). +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 ab7e23b0..98325e86 100644 --- a/.gitignore +++ b/.gitignore @@ -4,9 +4,15 @@ .DS_Store .ipynb_checkpoints .sass-cache +.jekyll-cache/ __pycache__ _site .Rproj.user .Rhistory .RData - +.bundle/ +.vendor/ +vendor/ +.docker-vendor/ +Gemfile.lock +.*history diff --git a/Gemfile b/Gemfile new file mode 100644 index 00000000..fb25ae48 --- /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/LICENSE.md b/LICENSE.md index fffa52f2..79b88169 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -5,7 +5,7 @@ root: . --- ## Instructional Material -All Software Carpentry and Data Carpentry instructional material is +All Software Carpentry, Data Carpentry, and Library Carpentry instructional material is made available under the [Creative Commons Attribution license][cc-by-human]. The following is a human-readable summary of (and not a substitute for) the [full legal text of the CC BY 4.0 diff --git a/Makefile b/Makefile index f0b73e60..b585662c 100644 --- a/Makefile +++ b/Makefile @@ -3,37 +3,67 @@ # Settings MAKEFILES=Makefile $(wildcard *.mk) -JEKYLL=jekyll -JEKYLL_VERSION=3.7.3 +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). -clear-rmd : +## * 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,38 +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} -# Use of .NOTPARALLEL makes rule execute only once -${RMD_DST} : ${RMD_SRC} - @bin/knit_lessons.sh ${RMD_SRC} +_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 new file mode 100644 index 00000000..d90e6d68 --- /dev/null +++ b/_includes/aio-script.md @@ -0,0 +1,25 @@ +{% comment %} +As a maintainer, you don't need to edit this file. +If you notice that something doesn't work, please +open an issue: https://github.com/carpentries/styles/issues/new +{% endcomment %} + +{% include manual_episode_order.html %} + +{% for lesson_episode in lesson_episodes %} + +{% if site.episode_order %} + {% assign e = site.episodes | where: "slug", lesson_episode | first %} +{% else %} + {% assign e = 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/all_keypoints.html b/_includes/all_keypoints.html index 8563df34..f0abd251 100644 --- a/_includes/all_keypoints.html +++ b/_includes/all_keypoints.html @@ -1,13 +1,22 @@ {% comment %} Display key points of all episodes for reference. {% endcomment %} + +{% include base_path.html %} +{% include manual_episode_order.html %} +

Key Points

-{% for episode in site.episodes %} +{% 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 %} {% unless episode.break %} \s*$/g,ra={option:[1,""],legend:[1,"
","
"],area:[1,"",""],param:[1,"",""],thead:[1,"
- {{ episode.title }} + {{ episode.title }}
","
"],tr:[2,"","
"],col:[2,"","
"],td:[3,"","
"],_default:k.htmlSerialize?[0,"",""]:[1,"X
","
"]},sa=da(y),ta=sa.appendChild(y.createElement("div"));ra.optgroup=ra.option,ra.tbody=ra.tfoot=ra.colgroup=ra.caption=ra.thead,ra.th=ra.td;function ua(a,b){var c,d,e=0,f=typeof a.getElementsByTagName!==K?a.getElementsByTagName(b||"*"):typeof a.querySelectorAll!==K?a.querySelectorAll(b||"*"):void 0;if(!f)for(f=[],c=a.childNodes||a;null!=(d=c[e]);e++)!b||m.nodeName(d,b)?f.push(d):m.merge(f,ua(d,b));return void 0===b||b&&m.nodeName(a,b)?m.merge([a],f):f}function va(a){W.test(a.type)&&(a.defaultChecked=a.checked)}function wa(a,b){return m.nodeName(a,"table")&&m.nodeName(11!==b.nodeType?b:b.firstChild,"tr")?a.getElementsByTagName("tbody")[0]||a.appendChild(a.ownerDocument.createElement("tbody")):a}function xa(a){return a.type=(null!==m.find.attr(a,"type"))+"/"+a.type,a}function ya(a){var b=pa.exec(a.type);return b?a.type=b[1]:a.removeAttribute("type"),a}function za(a,b){for(var c,d=0;null!=(c=a[d]);d++)m._data(c,"globalEval",!b||m._data(b[d],"globalEval"))}function Aa(a,b){if(1===b.nodeType&&m.hasData(a)){var c,d,e,f=m._data(a),g=m._data(b,f),h=f.events;if(h){delete g.handle,g.events={};for(c in h)for(d=0,e=h[c].length;e>d;d++)m.event.add(b,c,h[c][d])}g.data&&(g.data=m.extend({},g.data))}}function Ba(a,b){var c,d,e;if(1===b.nodeType){if(c=b.nodeName.toLowerCase(),!k.noCloneEvent&&b[m.expando]){e=m._data(b);for(d in e.events)m.removeEvent(b,d,e.handle);b.removeAttribute(m.expando)}"script"===c&&b.text!==a.text?(xa(b).text=a.text,ya(b)):"object"===c?(b.parentNode&&(b.outerHTML=a.outerHTML),k.html5Clone&&a.innerHTML&&!m.trim(b.innerHTML)&&(b.innerHTML=a.innerHTML)):"input"===c&&W.test(a.type)?(b.defaultChecked=b.checked=a.checked,b.value!==a.value&&(b.value=a.value)):"option"===c?b.defaultSelected=b.selected=a.defaultSelected:("input"===c||"textarea"===c)&&(b.defaultValue=a.defaultValue)}}m.extend({clone:function(a,b,c){var d,e,f,g,h,i=m.contains(a.ownerDocument,a);if(k.html5Clone||m.isXMLDoc(a)||!ga.test("<"+a.nodeName+">")?f=a.cloneNode(!0):(ta.innerHTML=a.outerHTML,ta.removeChild(f=ta.firstChild)),!(k.noCloneEvent&&k.noCloneChecked||1!==a.nodeType&&11!==a.nodeType||m.isXMLDoc(a)))for(d=ua(f),h=ua(a),g=0;null!=(e=h[g]);++g)d[g]&&Ba(e,d[g]);if(b)if(c)for(h=h||ua(a),d=d||ua(f),g=0;null!=(e=h[g]);g++)Aa(e,d[g]);else Aa(a,f);return d=ua(f,"script"),d.length>0&&za(d,!i&&ua(a,"script")),d=h=e=null,f},buildFragment:function(a,b,c,d){for(var e,f,g,h,i,j,l,n=a.length,o=da(b),p=[],q=0;n>q;q++)if(f=a[q],f||0===f)if("object"===m.type(f))m.merge(p,f.nodeType?[f]:f);else if(la.test(f)){h=h||o.appendChild(b.createElement("div")),i=(ja.exec(f)||["",""])[1].toLowerCase(),l=ra[i]||ra._default,h.innerHTML=l[1]+f.replace(ia,"<$1>")+l[2],e=l[0];while(e--)h=h.lastChild;if(!k.leadingWhitespace&&ha.test(f)&&p.push(b.createTextNode(ha.exec(f)[0])),!k.tbody){f="table"!==i||ka.test(f)?""!==l[1]||ka.test(f)?0:h:h.firstChild,e=f&&f.childNodes.length;while(e--)m.nodeName(j=f.childNodes[e],"tbody")&&!j.childNodes.length&&f.removeChild(j)}m.merge(p,h.childNodes),h.textContent="";while(h.firstChild)h.removeChild(h.firstChild);h=o.lastChild}else p.push(b.createTextNode(f));h&&o.removeChild(h),k.appendChecked||m.grep(ua(p,"input"),va),q=0;while(f=p[q++])if((!d||-1===m.inArray(f,d))&&(g=m.contains(f.ownerDocument,f),h=ua(o.appendChild(f),"script"),g&&za(h),c)){e=0;while(f=h[e++])oa.test(f.type||"")&&c.push(f)}return h=null,o},cleanData:function(a,b){for(var d,e,f,g,h=0,i=m.expando,j=m.cache,l=k.deleteExpando,n=m.event.special;null!=(d=a[h]);h++)if((b||m.acceptData(d))&&(f=d[i],g=f&&j[f])){if(g.events)for(e in g.events)n[e]?m.event.remove(d,e):m.removeEvent(d,e,g.handle);j[f]&&(delete j[f],l?delete d[i]:typeof d.removeAttribute!==K?d.removeAttribute(i):d[i]=null,c.push(f))}}}),m.fn.extend({text:function(a){return V(this,function(a){return void 0===a?m.text(this):this.empty().append((this[0]&&this[0].ownerDocument||y).createTextNode(a))},null,a,arguments.length)},append:function(){return this.domManip(arguments,function(a){if(1===this.nodeType||11===this.nodeType||9===this.nodeType){var b=wa(this,a);b.appendChild(a)}})},prepend:function(){return this.domManip(arguments,function(a){if(1===this.nodeType||11===this.nodeType||9===this.nodeType){var b=wa(this,a);b.insertBefore(a,b.firstChild)}})},before:function(){return this.domManip(arguments,function(a){this.parentNode&&this.parentNode.insertBefore(a,this)})},after:function(){return this.domManip(arguments,function(a){this.parentNode&&this.parentNode.insertBefore(a,this.nextSibling)})},remove:function(a,b){for(var c,d=a?m.filter(a,this):this,e=0;null!=(c=d[e]);e++)b||1!==c.nodeType||m.cleanData(ua(c)),c.parentNode&&(b&&m.contains(c.ownerDocument,c)&&za(ua(c,"script")),c.parentNode.removeChild(c));return this},empty:function(){for(var a,b=0;null!=(a=this[b]);b++){1===a.nodeType&&m.cleanData(ua(a,!1));while(a.firstChild)a.removeChild(a.firstChild);a.options&&m.nodeName(a,"select")&&(a.options.length=0)}return this},clone:function(a,b){return a=null==a?!1:a,b=null==b?a:b,this.map(function(){return m.clone(this,a,b)})},html:function(a){return V(this,function(a){var b=this[0]||{},c=0,d=this.length;if(void 0===a)return 1===b.nodeType?b.innerHTML.replace(fa,""):void 0;if(!("string"!=typeof a||ma.test(a)||!k.htmlSerialize&&ga.test(a)||!k.leadingWhitespace&&ha.test(a)||ra[(ja.exec(a)||["",""])[1].toLowerCase()])){a=a.replace(ia,"<$1>");try{for(;d>c;c++)b=this[c]||{},1===b.nodeType&&(m.cleanData(ua(b,!1)),b.innerHTML=a);b=0}catch(e){}}b&&this.empty().append(a)},null,a,arguments.length)},replaceWith:function(){var a=arguments[0];return this.domManip(arguments,function(b){a=this.parentNode,m.cleanData(ua(this)),a&&a.replaceChild(b,this)}),a&&(a.length||a.nodeType)?this:this.remove()},detach:function(a){return this.remove(a,!0)},domManip:function(a,b){a=e.apply([],a);var c,d,f,g,h,i,j=0,l=this.length,n=this,o=l-1,p=a[0],q=m.isFunction(p);if(q||l>1&&"string"==typeof p&&!k.checkClone&&na.test(p))return this.each(function(c){var d=n.eq(c);q&&(a[0]=p.call(this,c,d.html())),d.domManip(a,b)});if(l&&(i=m.buildFragment(a,this[0].ownerDocument,!1,this),c=i.firstChild,1===i.childNodes.length&&(i=c),c)){for(g=m.map(ua(i,"script"),xa),f=g.length;l>j;j++)d=i,j!==o&&(d=m.clone(d,!0,!0),f&&m.merge(g,ua(d,"script"))),b.call(this[j],d,j);if(f)for(h=g[g.length-1].ownerDocument,m.map(g,ya),j=0;f>j;j++)d=g[j],oa.test(d.type||"")&&!m._data(d,"globalEval")&&m.contains(h,d)&&(d.src?m._evalUrl&&m._evalUrl(d.src):m.globalEval((d.text||d.textContent||d.innerHTML||"").replace(qa,"")));i=c=null}return this}}),m.each({appendTo:"append",prependTo:"prepend",insertBefore:"before",insertAfter:"after",replaceAll:"replaceWith"},function(a,b){m.fn[a]=function(a){for(var c,d=0,e=[],g=m(a),h=g.length-1;h>=d;d++)c=d===h?this:this.clone(!0),m(g[d])[b](c),f.apply(e,c.get());return this.pushStack(e)}});var Ca,Da={};function Ea(b,c){var d,e=m(c.createElement(b)).appendTo(c.body),f=a.getDefaultComputedStyle&&(d=a.getDefaultComputedStyle(e[0]))?d.display:m.css(e[0],"display");return e.detach(),f}function Fa(a){var b=y,c=Da[a];return c||(c=Ea(a,b),"none"!==c&&c||(Ca=(Ca||m("