From 80314d9d960d31dab4ac4ff7b327eabe5cce6f68 Mon Sep 17 00:00:00 2001 From: Greg Wilson Date: Sat, 16 Apr 2016 15:04:24 -0400 Subject: [PATCH] Explaining tooling --- _config.yml | 7 +- _episodes/01-tooling.md | 120 ++++++++++++++++++++++------------- _episodes/03-organization.md | 7 +- 3 files changed, 85 insertions(+), 49 deletions(-) diff --git a/_config.yml b/_config.yml index 19981da..475d624 100644 --- a/_config.yml +++ b/_config.yml @@ -22,10 +22,11 @@ email: gvwilson@software-carpentry.org #------------------------------------------------------------ # Sites. -amy_site: "https://amy.software-carpentry.org/workshops" -dc_site: "https://datacarpentry.org" +amy_site: "https://amy.software-carpentry.org/workshops" +dc_site: "https://datacarpentry.org" swc_github: "https://github.com/swcarpentry" -swc_site: "https://software-carpentry.org" +swc_site: "https://software-carpentry.org" +template_repo: "https://github.com/gvwilson/new-lesson-template" # Start time in minutes (540 is 09:00 am) start_time: 540 diff --git a/_episodes/01-tooling.md b/_episodes/01-tooling.md index d10c856..9f39a6b 100644 --- a/_episodes/01-tooling.md +++ b/_episodes/01-tooling.md @@ -10,53 +10,67 @@ objectives: keypoints: - "FIXME" --- +This episode describes tools we use to manage lessons, +which simplify many tasks but make other things more complicated. + ## Repositores on GitHub -Git uses the term *clone* to mean "a copy of a repository". -GitHub uses the term *fork* to mean, "a copy of a GitHub-hosted -repo that is also hosted on GitHub", and the term *clone* to mean -"a copy of a GitHub-hosted repo that's located on someone else's -machine". In both cases, the duplicate has a remote called -`origin` that points to the original repo; other remotes can be -added manually. +All of our lessons are stored in Git repositories on GitHub. +Git uses the term *clone* to mean "a copy of a repository", +while GitHub uses the term *fork* to mean "a copy of a GitHub-hosted repo that is also hosted on GitHub" +and the term *clone* to mean "a copy of a GitHub-hosted repo that's located on someone else's machine". +In both cases, +the duplicate has a remote called `origin` that points to the original repo; +other remotes can be added manually. A user on GitHub can only have one fork of a particular repo. -This is a problem for us because an author may be involved in -writing several lessons, each of which has its own website repo. -Those website repositories ought to be forks of this one, but -since GitHub doesn't allow that, we've had to find a workaround. +This is a problem for us because an author may be involved in writing several lessons, +each of which has its own website repo. +Those website repositories ought to be forks of the [template repository]({{ site.template_repo }}), +but since GitHub doesn't allow that, +we use [GitHub Importer][github-importer] when creating new lessons. +After the lesson has been created, +we manually add the [template repository]({{ site.template_repo }}) as a remote called `template` +to update the lesson when the template changes. ## GitHub Pages -If a repository has a branch called `gh-pages` (which stands for -"GitHub pages"), then GitHub uses the HTML and Markdown files in -that branch to create a website for the repository. If the -repository's URL is `http://github.com/darwin/finches`, the URL -for the website is `http://darwin.github.io/finches`. +If a repository has a branch called `gh-pages` (short for "GitHub Pages"), +GitHub publishes its content to create a website for the repository. +If the repository's URL is `https://github.com/USERNAME/REPOSITORY`, +the website is `https://USERNAME.github.io/REPOSITORY`. + +Websites can be static HTML pages, +which are published as-is, +or can use the [Jekyll][jekyll] templating system described below. ## Markdown -We use Markdown for writing pages because it's simple to learn, -and isn't tied to any specific language (the ReStructured Text -format popular in the Python world, for example, is a complete -unknown to R programmers). If authors want to use something else -to author their lessons (e.g., Jupyter Notebooks), it's up to them -to generate and commit Markdown formatted according to the rules -below. +We use Markdown for lesson content because it's simple to learn +and isn't tied to any specific language +(the ReStructured Text format popular in the Python world, +for example, +is a complete unknown to R programmers). +If authors want to use something else to author their lessons, +such as [R Markdown][r-markdown], +they must generate Markdown that [Jekyll][jekyll] can process, +or static HTML, +and commit that to the repository. > ## Tooling > -> Note that we do *not* prescribe what tools instructors should use -> when actually teaching. The Jupyter Notebook, Python IDEs like -> Spyder, and the GOCLI (Good Ol' Command Line Interpreter) are all -> equally welcome up on stage --- all we specify is the format of -> the lesson notes. +> We do *not* prescribe what tools instructors should use when actually teaching: +> the [Jupyter Notebook][jupyter], +> [RStudio][rstudio], +> and the good ol' command line are equally welcome up on stage. +> All we specify is the format of the lesson notes. {: .callout} ## Jekyll -GitHub uses Jekyll to turn Markdown into HTML. Jekyll looks for -a header at the top of each page formatted like this: +GitHub uses [Jekyll][jekyll] to turn Markdown into HTML. +By default, +it looks for text files that begin with a header formatted like this: ~~~ --- @@ -67,18 +81,34 @@ other_variable: other_value ~~~ {: .source} -and inserts the values of those variables into the page when -formatting this. Lesson authors will usually not have to worry -about this. - -Jekyll also takes values from a `_config.yml` configuration file -and inserts them into the page. Lesson authors will also not -have to worry about this in most cases, provided they update the -`title`, `lesson_repo`, and `lesson_site` variables in `_config.yml`. - -In order to display properly, our generated HTML pages need artwork, -CSS style files, and a few bits of Javascript. We could load these -from the web, but that would make offline authoring difficult. -Instead, each lesson's repository is self-contained and has a copy of -all these third party resources, and a way of updating them (and only -them) on demand. +and inserts the values of those variables into the page when formatting this. +The three dashes that start the header *must* be the first three characters in the file: +even a single space before them will make [Jekyll][jekyll] ignore the file. + +Jekyll requires the header to be formatted as [YAML][yaml], +which provides Booleans, numbers, character strings, lists, and dictionaries of name/value pairs. +Values from the header are referred to in the page as `page.variable`. + +## Configuration + +Jekyll also reads values from a configuration file called `_config.yml`, +which are referred to in the page as `site.variable`. +The [lesson template]({{ site.template_repo }}) does *not* include `_config.yml`, +since each lesson will change some of its value, +which would result in merge collisions each time the lesson was updated from the template. +Instead, +the [template]({{ site.template_repo }}) contains `_config_template.yml`; +authors should copy this file to create `_config.yml` +and then edit values in the top half. + +The [template]({{ site.template_repo }}) also contains `_config_dev.yml`, +which overrides some settings for use during desktop development. +The Makefile that comes with the [template]({{ site.template_repo }}) +adds these values to those in `_config.yml` when running a local server. + +[github-importer]: https://import.github.com/ +[jekyll]: http://jekyllrb.com/ +[jupyter]: https://jupyter.org/ +[r-markdown]: http://rmarkdown.rstudio.com/ +[rstudio]: https://www.rstudio.com/ +[yaml]: http://yaml.org/ diff --git a/_episodes/03-organization.md b/_episodes/03-organization.md index ab1518a..abf197f 100644 --- a/_episodes/03-organization.md +++ b/_episodes/03-organization.md @@ -11,7 +11,12 @@ keypoints: --- ## Common Files -FIXME +In order to display properly, our generated HTML pages need artwork, +CSS style files, and a few bits of Javascript. We could load these +from the web, but that would make offline authoring difficult. +Instead, each lesson's repository is self-contained and has a copy of +all these third party resources, and a way of updating them (and only +them) on demand. ## Layouts -- GitLab