Bring latest styles (#645)

* links.md: lesson-specific links

* .travis.yml: use Python 3.7

Signed-off-by: Maxim Belkin <maxim.belkin@gmail.com>

* links.md: sync with downstream (lesson-example)

* lesson_check.py: require _config.yml too

* knit_lessons.sh: require 2 inputs exactly

* update link for coc reporting

* Clarify wording of PR & issue templates

I see lots of contributions where none of this placeholder text has
been deleted, but also quite a lot where the first line has been deleted,
but the 'ext below' hasn't (exactly in accordance with the current
instructions).

* lesson_check.py: remove _config.yml from the list of required files

Pull Request: carpentries/styles#388

* Colorize all boxes

Use the same colors but apply 12.5% opacity.

Solution boxes use 30% opacity

* Improve contrast of code elements

* Prefix code blocks with language names

Also, improve contrast of comments

Signed-off-by: Maxim Belkin <maxim.belkin@gmail.com>

* Fix contrast of links in challenge blocks

* reference to the webpage of the lesson + goodfirst

This contribution adds reference to the web page of the lesson in the Carpentries and makes it easier for visitors who want to contribute to get familiar with the good first issue badge.
This adds a list of current maintainers to the README.md.

* gold colour to badge

gold looks more like the yellow from the original badge

* add 'FIXME' so they will be picked up by checks

* use xenial on travis

* bin/lesson_check.py: avoid inconsistent grammar

Pull Request: carpentries/styles#396

* util.py: hot fix for YAML loader

* add data-checker-ignore attributes to links that only work on GitHub

* add data-checker-ignore attributes to footer links

* make title show episode title first

* use ndash as separator

display it only if both `page.title` and `site.title` are defined.

* upgrade to bootstrap 3.4.1

* update coc incident reporting link

* Update PULL_REQUEST_TEMPLATE.md

* Update ISSUE_TEMPLATE.md

* links.md: fix lesson-setup link

* links.md: include base_path.html

* aio.md: multiple improvements

Pull Request: carpentries/styles#406

* change all-in-one file to have the same 'depth' as episode files

* move the core script of aio.md into _includes/aio-script.md

* include comment to inform maintainers to not edit the file

* move aio.md to the root of styles repository

* [fix #408] remove aio from files that need to be initialized

* lesson-check: exclude aio.md, fix read_references

* bump jekyll version to match github pages version

https://pages.github.com/versions/

* Callout (and other) blocks: proper font size, margins

* Use darker purple for code blocks

* Use 1px borders: fix Google Chrome & Edge

See swcarpentry/git-novice#662 (comment)

* specify language based on engine

- fix swcarpentry/r-novice-inflammation#436

* Ignore Jekyll 4's cache

See https://jekyllrb.com/news/2019/08/20/jekyll-4-0-0-released/#cache-all-the-things- & https://github.com/jekyll/jekyll/releases/tag/v4.0.0

It appears during `make site` & `make serve`.

* assets/css/lesson.scss: add proper padding to the top of paragraphs in blockquotes (#425)

* restore lost CSS settings

* Manual ordering of episodes and extras

Co-authored-by: stamper <tbyhdgs@gmail.com>

* [fix #513] remove site.title outside

lessons

* update survey links

* Switch to Liquid comments

HTML comments end up in the generated HTML pages: they're not displayed by the browsers but they're still present there. Liquid comments do not end up in the generated HTML pages

* bin/boilerplate/README.md: fix typo

carpentries/styles#441

* Use Jekyll to generate the 'all-in-one' page (carpentries/styles#438)

* manual_episode_order.html: fix typo in a comment

* Enable 'Sponsor' button on GitHub repos

* remove Jekyll command markers from comment block

fix carpentries/lesson-example#281

* Forced re-encoding of text to UTF-8, to avoid issues on Windows

* Refactored paths to make use of OS agnostic methods

* Modified shebang to use python, not python3.

* Reverted change of permissiveness on lesson_check

* Cleaned leftover debug code and old implementations.

* Added PYTHON variable to define executable to run python scripts

* Reverted variable names

* Removed shebang lines from Python scripts to avoid cross-OS problems

* Fixes encoding problem on Windows systems, with minimal changes to existing code.

* Silenced output of PYTHON calls

* Makefile: detect Python 3

* util.py: remove empty line

* Undo optimizations to read_all_markdown

These will be submitted in a separate PR

* Remove executable bits from Python scripts

We can't use a single shebang:
* on some platforms `python` may mean Python 2, on others - Python 3
* on some platforms `python3` does not exist at all

Therefore, we're removing the shebangs altogether.

* lesson_initialize: windows compatibility

* lesson_check.py: Windows-compatible regular expression pattern

* repo_check.py: enforce utf-8 encoding

... for compatibility with Windows

* clarify comment on python check block

* Makefile: Windows does not like single quotes

* test_lesson_check.py: skip unnecessary steps

* Makefile: suppress error message on Windows

* fix typo in lesson_initialize.py

* Makefile: suppress another error message on Windows

These '2>/dev/null' are important on Windows because without them
a mere `make` stalls.

* Makefile: handle MS Store's Python 3

* Makefile: fix syntax in conditional

* Makefile: fix two more syntax errors in conditionals

* fix urls in _config.yml

* use bundler to render lessons

* install gems locally

* refactor use of docker

Co-authored-by: Allen Lee <allen.lee@asu.edu>

* add @maxim-belkin suggestions

* add .bundle to .gitignore

* Makefile: Specify shell. Don't include commands.mk

* Makefile: use Python to execute repo_check.py

* Makefile: improve commands target and commands categories (#450)

* Makefile: improve commands target and commands categories

* replace 'files' with 'website'

* Update R install in .travis.yml (#430)

* Update R install in .travis.yml

See https://cran.r-project.org/bin/linux/ubuntu/README.html

* update .travis.yml

.github/FUNDING.yml

@@ -0,0 +1,2 @@
+github: [carpentries, swcarpentry, datacarpentry, librarycarpentry]
+custom: ["https://carpentries.wedid.it"]

.github/ISSUE_TEMPLATE.md

@@ -6,6 +6,6 @@ Thanks for contributing! If this contribution is for instructor training, please
 
 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 Kate Hertweck (k8hertweck@gmail.com).  
+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.  
 
 ---

.github/PULL_REQUEST_TEMPLATE.md

@@ -4,6 +4,6 @@ Please delete this line and the text below before submitting your contribution.
 
 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.  
 
-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).  
+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.  
 
 ---

.gitignore

@@ -3,9 +3,13 @@
 .DS_Store
 .ipynb_checkpoints
 .sass-cache
+.jekyll-cache/
 __pycache__
 _site
 .Rproj.user
 .Rhistory
 .RData
-
+.bundle/
+.vendor/
+.docker-vendor/
+Gemfile.lock

Gemfile

@@ -1,2 +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.3'
+
 gem 'github-pages', group: :jekyll_plugins

Makefile

@@ -1,39 +1,70 @@
+# Use /bin/bash instead of /bin/sh
+export SHELL = /bin/bash
+
 ## ========================================
 ## Commands for both workshop and lesson websites.
 
 # Settings
 MAKEFILES=Makefile $(wildcard *.mk)
-JEKYLL=jekyll
-JEKYLL_VERSION=3.7.3
+JEKYLL_VERSION=3.8.5
+JEKYLL=bundle install --path .vendor/bundle && 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 run --rm -it --volume ${PWD}:/srv/jekyll \
+           --volume=${PWD}/.docker-vendor/bundle:/usr/local/bundle \
+           -p 127.0.0.1:4000:4000 \
+           jekyll/jekyll:${JEKYLL_VERSION} \
+           bin/run-make-docker-serve.sh
+
+## * 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 +73,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 +120,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
 
-#-------------------------------------------------------------------------------
-# 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)

_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 %}
+
+<h1 id="{{ e.title | slugify }}" class="maintitle">{{ e.title }}</h1>
+
+{% 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 %}
+<hr />
+{% endfor %}

_includes/all_keypoints.html

@@ -3,10 +3,16 @@
 {% endcomment %}
 
 {% include base_path.html %}
+{% include manual_episode_order.html %}
 
 <h2>Key Points</h2>
 <table class="table table-striped">
-{% 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 %}
     <tr>
       <td class="col-md-3">

_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 %}
+
 <blockquote class="keypoints">
   <h2>Key Points</h2>
   <ul>
-    {% for keypoint in page.keypoints %}
+    {% for keypoint in episode_keypoints %}
     <li>{{ keypoint|markdownify }}</li>
     {% endfor %}
   </ul>

_includes/episode_navbar.html

@@ -9,11 +9,17 @@
   Navigation bar for an episode.
 {% endcomment %}
 
+{% include manual_episode_order.html %}
+{% comment %}
+    'previous_episode' and 'next_episodes' are defined in 'manual_episode_order.html'.
+    These replace 'page.previous' and 'page.next' objects, correspondingly.
+{% endcomment %}
+
 <div class="row">
   <div class="col-xs-1">
     <h3 class="text-left">
-      {% if page.previous.url %}
-      <a href="{{ relative_root_path }}{{ page.previous.url }}"><span class="glyphicon glyphicon-menu-left" aria-hidden="true"></span><span class="sr-only">previous episode</span></a>
+      {% if previous_episode %}
+      <a href="{{ relative_root_path }}{{ previous_episode.url }}"><span class="glyphicon glyphicon-menu-left" aria-hidden="true"></span><span class="sr-only">previous episode</span></a>
       {% else %}
       <a href="{{ relative_root_path }}/"><span class="glyphicon glyphicon-menu-up" aria-hidden="true"></span><span class="sr-only">lesson home</span></a>
       {% endif %}
@@ -26,8 +32,8 @@ <h3 class="maintitle"><a href="{{ relative_root_path }}/">{{ site.title }}</a></
   </div>
   <div class="col-xs-1">
     <h3 class="text-right">
-      {% if page.next.url %}
-      <a href="{{ relative_root_path }}{{ page.next.url }}"><span class="glyphicon glyphicon-menu-right" aria-hidden="true"></span><span class="sr-only">next episode</span></a>
+      {% if next_episode %}
+      <a href="{{ relative_root_path }}{{ next_episode.url }}"><span class="glyphicon glyphicon-menu-right" aria-hidden="true"></span><span class="sr-only">next episode</span></a>
       {% else %}
       <a href="{{ relative_root_path }}/"><span class="glyphicon glyphicon-menu-up" aria-hidden="true"></span><span class="sr-only">lesson home</span></a>
       {% endif %}

_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 %}
+
+
 <blockquote class="objectives">
   <h2>Overview</h2>
 
   <div class="row">
     <div class="col-md-3">
-      <strong>Teaching:</strong> {{ page.teaching }} min
+      <strong>Teaching:</strong> {{ teaching_time }} min
       <br/>
-      <strong>Exercises:</strong> {{ page.exercises }} min
+      <strong>Exercises:</strong> {{ exercise_time }} min
     </div>
     <div class="col-md-9">
       <strong>Questions</strong>
       <ul>
-	{% for question in page.questions %}
+	{% for question in episode_questions %}
 	<li>{{ question|markdownify }}</li>
 	{% endfor %}
       </ul>
@@ -26,7 +66,7 @@ <h2>Overview</h2>
     <div class="col-md-9">
       <strong>Objectives</strong>
       <ul>
-	{% for objective in page.objectives %}
+	{% for objective in episode_objectives %}
 	<li>{{ objective|markdownify }}</li>
 	{% endfor %}
       </ul>