Merge pull request #186 from datacarpentry/update-styles-final

Update to final version of styles lesson template

Author: tobyhodges

.github/PULL_REQUEST_TEMPLATE.md

@@ -4,7 +4,7 @@
 Thanks for contributing! :heart:
 
 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
+instructor.training@carpentries.org so we can record your progress. You've completed your contribution
 step for instructor checkout by submitting this contribution!
 
 Keep in mind that **lesson maintainers are volunteers** and it may take them some time to

.github/workflows/template.yml

@@ -8,14 +8,16 @@ jobs:
     name: ${{ matrix.lesson-name }} (${{ matrix.os-name }})
     if: github.repository == 'carpentries/styles'
     runs-on: ${{ matrix.os }}
+    continue-on-error: ${{ matrix.experimental }}
     strategy:
       fail-fast: false
       matrix:
         lesson: [swcarpentry/shell-novice, datacarpentry/r-intro-geospatial, librarycarpentry/lc-git]
         os: [ubuntu-20.04, macos-latest, windows-latest]
+        experimental: [false]
         include:
           - os: ubuntu-20.04
-            os-name: Ubuntu
+            os-name: Linux
           - os: macos-latest
             os-name: macOS
           - os: windows-latest
@@ -26,6 +28,16 @@ jobs:
             lesson-name: (DC) R Intro Geospatial
           - lesson: librarycarpentry/lc-git
             lesson-name: (LC) Intro to Git
+          - lesson: datacarpentry/astronomy-python
+            lesson-name: (DC) Foundations of Astronomical Data Science
+            experimental: true
+            os: ubuntu-20.04
+            os-name: Linux
+          - lesson: carpentries/lesson-example
+            lesson-name: (CP) Lesson Example
+            experimental: false
+            os: ubuntu-20.04
+            os-name: Linux
     defaults:
       run:
         shell: bash # forces 'Git for Windows' on Windows
@@ -62,25 +74,54 @@ jobs:
           path: lesson
           fetch-depth: 0
 
-      - name: Determine the proper reference to use
-        id: styles-ref
+      - name: Sync lesson with carpentries/styles
+        working-directory: lesson
         run: |
-          if [[ -n "${{ github.event.pull_request.number }}" ]]; then
-            echo "::set-output name=ref::refs/pull/${{ github.event.pull_request.number }}/head"
+          echo "::group::Fetch Styles"
+          if [[ -n "${{ github.event.pull_request.number }}" ]]
+          then
+            ref="refs/pull/${{ github.event.pull_request.number }}/head"
           else
-            echo "::set-output name=ref::gh-pages"
+            ref="gh-pages"
           fi
 
-      - name: Sync lesson with carpentries/styles
-        working-directory: lesson
-        run: |
           git config --global user.email "[email protected]"
           git config --global user.name "The Carpentries Bot"
+
           git remote add styles https://github.com/carpentries/styles.git
-          git config --local remote.styles.tagOpt --no-tags
-          git fetch styles ${{ steps.styles-ref.outputs.ref }}:styles-ref
-          git merge -s recursive -Xtheirs --no-commit styles-ref
-          git commit -m "Sync lesson with carpentries/styles"
+          git fetch styles $ref:styles-ref
+          echo "::endgroup::"
+          echo "::group::Synchronize Styles"
+          # Sync up only if necessary
+          if [[ $(git rev-list --count HEAD..styles-ref) != 0 ]]
+          then
+
+            # The merge command below might fail for lessons that use remote theme
+            # https://github.com/carpentries/carpentries-theme
+            echo "Testing merge using recursive strategy, accepting upstream changes without committing"
+            if ! git merge -s recursive -Xtheirs --no-commit styles-ref
+            then
+
+              # Remove "deleted by us, unmerged" files from the staging area.
+              # these are the files that were removed from the lesson
+              # but are still present in the carpentries/styles repo
+              echo "Removing previously deleted files"
+              git rm $(git diff --name-only --diff-filter=DU)
+
+              # If there are still "unmerged" files,
+              # let's raise an error and look into this more closely
+              if [[ -n $(git diff --name-only --diff-filter=U) ]]
+              then
+                echo "There were unmerged files in ${{ matrix.lesson-name }}:"
+                echo "$(git diff --compact-summary --diff-filter=U)"
+                exit 1
+              fi
+            fi
+
+            echo "Committing changes"
+            git commit -m "Sync lesson with carpentries/styles"
+          fi
+          echo "::endgroup::"
 
       - name: Look for R-markdown files
         id: check-rmd
@@ -94,13 +135,13 @@ jobs:
         with:
           use-public-rspm: true
           install-r: false
-          r-version: 'release'
 
       - name: Install needed packages
         if: steps.check-rmd.outputs.count != 0
+        working-directory: lesson
         run: |
-          packages = setdiff(c('remotes', 'rprojroot', 'renv', 'desc', 'rmarkdown', 'knitr'), rownames(installed.packages()))
-          install.packages(packages, repo="https://cran.rstudio.com/")
+          source('bin/dependencies.R')
+          install_required_packages(.libPaths()[1])
         shell: Rscript {0}
 
       - name: Query dependencies
@@ -110,13 +151,14 @@ jobs:
           source('bin/dependencies.R')
           deps <- identify_dependencies()
           create_description(deps)
+          use_bioc_repos()
           saveRDS(remotes::dev_package_deps(dependencies = TRUE), ".github/depends.Rds", version = 2)
           writeLines(sprintf("R-%i.%i", getRversion()$major, getRversion()$minor), ".github/R-version")
         shell: Rscript {0}
 
-      - name: Cache R packages
+      - name: Restore Package Cache
         if: runner.os != 'Windows' && steps.check-rmd.outputs.count != 0
-        uses: actions/cache@v1
+        uses: actions/cache@v2
         with:
           path: ${{ env.R_LIBS_USER }}
           key: ${{ runner.os }}-${{ hashFiles('.github/R-version') }}-1-${{ hashFiles('.github/depends.Rds') }}
@@ -133,8 +175,11 @@ jobs:
         run: |
           while read -r cmd
           do
-            eval sudo $cmd
+            eval sudo $cmd || echo "Nothing to update"
           done < <(Rscript -e 'cat(remotes::system_requirements("ubuntu", "20.04"), sep = "\n")')
 
       - run: make site
         working-directory: lesson
+
+      - run: make lesson-check-all
+        working-directory: lesson

.github/workflows/website.yml

@@ -52,11 +52,10 @@ jobs:
         with:
           use-public-rspm: true
           install-r: false
-          r-version: 'release'
 
-      - name: Cache R packages
+      - name: Restore R Cache
         if: steps.check-rmd.outputs.count != 0
-        uses: actions/cache@v1
+        uses: actions/cache@v2
         with:
           path: ${{ env.R_LIBS_USER }}
           key: ${{ runner.os }}-${{ hashFiles('.github/R-version') }}-1-${{ hashFiles('.github/depends.Rds') }}
@@ -65,8 +64,8 @@ jobs:
       - name: Install needed packages
         if: steps.check-rmd.outputs.count != 0
         run: |
-          packages = setdiff(c('remotes', 'rprojroot', 'renv', 'desc', 'rmarkdown', 'knitr'), rownames(installed.packages()))
-          install.packages(packages, repo="https://cran.rstudio.com/")
+          source('bin/dependencies.R')
+          install_required_packages()
         shell: Rscript {0}
 
       - name: Query dependencies
@@ -75,6 +74,7 @@ jobs:
           source('bin/dependencies.R')
           deps <- identify_dependencies()
           create_description(deps)
+          use_bioc_repos()
           saveRDS(remotes::dev_package_deps(dependencies = TRUE), ".github/depends.Rds", version = 2)
           writeLines(sprintf("R-%i.%i", getRversion()$major, getRversion()$minor), ".github/R-version")
         shell: Rscript {0}
@@ -85,7 +85,7 @@ jobs:
         run: |
           while read -r cmd
           do
-            eval sudo $cmd
+            eval sudo $cmd || echo "Nothing to update"
           done < <(Rscript -e 'cat(remotes::system_requirements("ubuntu", "20.04"), sep = "\n")')
 
       - name: Render the markdown and confirm that the site can be built

404.md

@@ -5,12 +5,12 @@ permalink: 404.html
 title: "Page not found"
 ---
 
-# Oops! We can't find that page.
+# Oops! We cannot find that page.
 {: style="text-align: center;"}
 
 > ## Our apologies!
 >
-> We can't seem to find the page you're looking for.
+> We cannot seem to find the page you are looking for.
 > Try going back to the <a href="javascript:history.back()">previous page</a> or
 > navigate to any other page using the navigation bar above
 > {%- if site.kind == "lesson" -%} or the schedule below {%- endif -%}.

CODE_OF_CONDUCT.md

@@ -8,4 +8,5 @@ we pledge to follow the [Carpentry Code of Conduct][coc].
 Instances of abusive, harassing, or otherwise unacceptable behavior
 may be reported by following our [reporting guidelines][coc-reporting].
 
-{% include links.md %}
+[coc]: https://docs.carpentries.org/topic_folders/policies/code-of-conduct.html
+[coc-reporting]: https://docs.carpentries.org/topic_folders/policies/incident-reporting.html

LICENSE.md

@@ -23,13 +23,15 @@ license terms.
 
 Under the following terms:
 
-* **Attribution**---You must give appropriate credit (mentioning that
-  your work is derived from work that is Copyright © Software
-  Carpentry and, where practical, linking to
-  http://software-carpentry.org/), provide a [link to the
-  license][cc-by-human], and indicate if changes were made. You may do
-  so in any reasonable manner, but not in any way that suggests the
-  licensor endorses you or your use.
+* **Attribution**---You must give appropriate credit by:
+  - mentioning that your work is derived from work that is
+    Copyright © Software Carpentry, Data Carpentry, Library Carpentry,
+    or The Carpentries.
+  - where practical, linking to the respective lesson program website
+    (https://software-carpentry.org/, https://datacarpentry.org, https://librarycarpentry.org, or
+    https://carpentries.org), provide a [link to the license][cc-by-human]
+  - and indicate if changes were made. You may do so in any reasonable manner, but not in any way
+    that suggests the licensor endorses you or your use.
 
 **No additional restrictions**---You may not apply legal terms or
 technological measures that legally restrict others from doing
@@ -73,8 +75,8 @@ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 ## Trademark
 
-"Software Carpentry" and "Data Carpentry" and their respective logos
-are registered trademarks of [Community Initiatives][CI].
+"The Carpentries", "Software Carpentry" and "Data Carpentry" and their respective logos are
+registered trademarks of [Community Initiatives][CI].
 
 [cc-by-human]: https://creativecommons.org/licenses/by/4.0/
 [cc-by-legal]: https://creativecommons.org/licenses/by/4.0/legalcode

Makefile

@@ -7,6 +7,9 @@ JEKYLL=bundle config set --local path .vendor/bundle && bundle install && bundle
 PARSER=bin/markdown_ast.rb
 DST=_site
 
+# Find Docker
+DOCKER := $(shell which docker 2>/dev/null)
+
 # 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)
@@ -41,23 +44,27 @@ endif
 .PHONY: site docker-serve repo-check clean clean-rmd
 
 ## * serve            : render website and run a local server
-serve : lesson-md
+serve : lesson-md index.md
 	${JEKYLL} serve
 
 ## * site             : build website but do not run a server
-site : lesson-md
+site : lesson-md index.md
 	${JEKYLL} build
 
 ## * docker-serve     : use Docker to serve the site
 docker-serve :
-	@docker pull carpentries/lesson-docker:latest
-	@docker run --rm -it \
+ifeq (, $(DOCKER))
+	$(error Your system does not appear to have Docker installed)
+else
+	@$(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
+endif
 
 ## * repo-check       : check repository settings
 repo-check : python
@@ -172,3 +179,10 @@ ifeq (, $(PYTHON))
 else
 	@:
 endif
+
+index.md :
+ifeq (, $(wildcard index.md))
+	$(error index.md not found)
+else
+	@:
+endif

_includes/base_path.html

@@ -1,27 +1,41 @@
-{% comment %}
-This is adapted from: https://ricostacruz.com/til/relative-paths-in-jekyll
+{%- comment -%}
+When the website is built by GitHub Pages,
+'site.url' is set to 'https://username.github.io'
+'site.baseurl' is set to '/lesson-name'
 
-`page.url` gives the URL of the current page with a leading /:
+When we start a local server using `jekyll serve`,
+'site.url' is set to 'http://localhost:4000' and
+'site.baseurl' is empty.
 
-- when the URL ends with the extension (e.g., /foo/bar.html) then we can get
-  the depth by counting the number of / and remove - 1
-- when the URL ends with a / (e.g. /foo/bar/) then the number / gives the depth
-  directly
-{% endcomment %}
+In both of the above cases we set 'relative_root_path' to 'site.baseurl'.
 
-{% assign relative_root_path = '' %}
+When we build a website locally with `jekyll build`,
+both 'site.url' and 'site.baseurl' are empty.
+This case is handled by the last 'else' in the code below.
+The logic there follows the (adapted) instructions found at:
+    https://ricostacruz.com/til/relative-paths-in-jekyll
 
-{% assign last_char = page.url | slice: -1 %}
+    `page.url` gives the URL of the current page with a leading /:
 
-{% if last_char == "/"}
-{% assign offset = 0 %}
-{% else %}
-{% assign offset = 1 %}
-{% endif %}
+    - when the URL ends with an extension (e.g., /foo/bar.html),
+      we can get the 'depth' of the page by counting the number of
+      forward slashes ('/') and subtracting 1
+    - when the URL ends with a forward slash (e.g. /foo/bar/),
+      we can get the depth of the page by counting the number of /
+{%- endcomment -%}
 
-{% assign depth = page.url | split: '/' | size | minus: offset %}
-{% if    depth <= 1 %}{% assign relative_root_path = '.' %}
-{% elsif depth == 2 %}{% assign relative_root_path = '..' %}
-{% elsif depth == 3 %}{% assign relative_root_path = '../..' %}
-{% elsif depth == 4 %}{% assign relative_root_path = '../../..' %}
+{% if site.url %}
+  {% assign relative_root_path = site.baseurl %}
+{% else %}
+  {% assign last_char = page.url | slice: -1 %}
+  {% if last_char == "/" %}
+    {% assign offset = 0 %}
+  {% else %}
+    {% assign offset = 1 %}
+  {% endif %}
+  {% assign depth = page.url | split: '/' | size | minus: offset %}
+  {% if    depth <= 1 %}{% assign relative_root_path = '.' %}
+  {% elsif depth == 2 %}{% assign relative_root_path = '..' %}
+  {% else %}{% capture relative_root_path %}..{% for i in (3..depth) %}/..{% endfor %}{% endcapture %}
+  {% endif %}
 {% endif %}

_includes/check_transition_variables.html

@@ -0,0 +1,22 @@
+{% assign date = include.need_transition_date %}
+
+{% if date == "true" %}
+{% unless site.transition_date_prebeta %}
+<div class="alert alert-danger">
+  you need to specify the variable <code>transition_date_prebeta</code>
+  in <code>_config.yml</code>.
+</div>
+{% endunless %}
+{% unless site.transition_date_beta %}
+<div class="alert alert-danger">
+  you need to specify the variable <code>transition_date_beta</code>
+  in <code>_config.yml</code>.
+</div>
+{% endunless %}
+{% unless site.transition_date_prerelease %}
+<div class="alert alert-danger">
+  you need to specify the variable <code>transition_date_prerelease</code>
+  in <code>_config.yml</code>.
+</div>
+{% endunless %}
+{% endif %}