Merge pull request #936

Sync up with carpentries/styles: June 2021

Author: maxim-belkin

.github/workflows/template.yml

@@ -137,9 +137,10 @@ jobs:
 
       - 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
@@ -149,13 +150,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') }}
@@ -172,7 +174,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")')
 
       - run: make site

.github/workflows/website.yml

@@ -52,9 +52,9 @@ jobs:
         with:
           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') }}
@@ -63,8 +63,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
@@ -73,6 +73,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}
@@ -83,7 +84,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

_includes/javascript.html

@@ -4,6 +4,7 @@
 <script src="{{ relative_root_path }}/assets/js/jquery.min.js"></script>
 <script src="{{ relative_root_path }}/assets/js/bootstrap.min.js"></script>
 <script src="{{ relative_root_path }}/assets/js/lesson.js"></script>
+
 <script>
   (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
   (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
@@ -12,6 +13,7 @@
   ga('create', 'UA-37305346-2', 'auto');
   ga('send', 'pageview');
 </script>
+
 {% if page.math %}
 <script src="{{ relative_root_path }}/assets/js/katex.min.js"></script>
 <script>
@@ -28,3 +30,13 @@
 <script src="{{ relative_root_path }}/assets/js/katex-auto-render.min.js" onload="renderMathInElement(document.body, options)"></script>
 {% endif %}
 
+{%- comment -%}
+AnchorJS: A JavaScript utility for adding deep anchor links
+https://github.com/bryanbraun/anchorjs
+https://cdn.jsdelivr.net/npm/anchor-js/anchor.min.js
+{%- endcomment -%}
+
+<script src="{{ relative_root_path }}/assets/js/anchor.min.js"></script>
+<script>
+    anchors.add();
+</script>

assets/css/lesson.scss

@@ -258,6 +258,11 @@ article img {
     max-width: 100%;
 }
 
+article img.inline {
+    display: inline-block;
+    margin: auto;
+}
+
 article h2 {
   margin: 48px 0 16px;
   border-bottom: solid 1px #eaecef;

assets/js/anchor.min.js

@@ -1,17 +1,19 @@
 install_required_packages <- function(lib = NULL, repos = getOption("repos", default = c(CRAN = "https://cran.rstudio.com/"))) {
 
   if (is.null(lib)) {
-    lib <- .libPaths()
+    lib <- .libPaths()[[1]]
   }
 
   message("lib paths: ", paste(lib, collapse = ", "))
-  required_pkgs <- c("rprojroot", "desc", "remotes", "renv")
+  # Note: RMarkdown is needed for renv to detect packages in Rmd documents.
+  required_pkgs <- c("rprojroot", "desc", "remotes", "renv", "BiocManager", "rmarkdown")
   installed_pkgs <- rownames(installed.packages(lib.loc = lib))
   missing_pkgs <- setdiff(required_pkgs, installed_pkgs)
 
-  # The default installation of R will have "@CRAN@" as the default repository, which directs contrib.url() to either
-  # force the user to choose a mirror if interactive or fail if not. Since we are not interactve, we need to force the
-  # mirror here.
+  # The default installation of R will have "@CRAN@" as the default repository,
+  # which directs contrib.url() to either force the user to choose a mirror if
+  # interactive or fail if not. Since we are not interactve, we need to force
+  # the mirror here.
   if ("@CRAN@" %in% repos) {
     repos <- c(CRAN = "https://cran.rstudio.com/")
   }
@@ -29,30 +31,73 @@ find_root <- function() {
   root
 }
 
+# set the BiocManager repositories and return a function that resets the default
+# repositories.
+#
+# @example
+# bioc_repos_example <- function() {
+#   message("User repos")
+#   as.data.frame(getOption("repos"))
+#   reset_repos <- use_bioc_repos()
+#   on.exit(reset_repos())
+#   message("Bioc repos")
+#   as.data.frame(getOption("repos"))
+# }
+# bioc_repos_example()
+# as.data.frame(getOption("repos")
+use_bioc_repos <- function() {
+  repos <- getOption("repos")
+  suppressMessages(options(repos = BiocManager::repositories()))
+  function() {
+    options(repos = repos)
+  }
+}
+
 identify_dependencies <- function() {
 
   root <- find_root()
 
+  reset_repos <- use_bioc_repos()
+  on.exit(reset_repos(), add = TRUE)
+  eps <- file.path(root, "_episodes_rmd")
+  bin <- file.path(root, "bin")
+
   required_pkgs <- unique(c(
     ## Packages for episodes
-    renv::dependencies(file.path(root, "_episodes_rmd"), progress = FALSE, error = "ignore")$Package,
+    renv::dependencies(eps, progress = FALSE, error = "ignored")$Package,
     ## Packages for tools
-    renv::dependencies(file.path(root, "bin"), progress = FALSE, error = "ignore")$Package
+    renv::dependencies(bin, progress = FALSE, error = "ignored")$Package
   ))
 
   required_pkgs
 }
 
 create_description <- function(required_pkgs) {
   d <- desc::description$new("!new")
-  lapply(required_pkgs, function(x) d$set_dep(x))
+  d$set_deps(data.frame(type = "Imports", package = required_pkgs, version = "*"))
   d$write("DESCRIPTION")
+  # We have to write the description twice to get the hidden dependencies
+  # because renv only considers explicit dependencies.
+  #
+  # This is needed because some of the hidden dependencis will require system
+  # libraries to be configured.
+  suppressMessages(repo <- BiocManager::repositories())
+  deps <- remotes::dev_package_deps(dependencies = TRUE, repos = repo)
+  deps <- deps$package[deps$diff < 0]
+  if (length(deps)) {
+    # only create new DESCRIPTION file if there are dependencies to install
+    d$set_deps(data.frame(type = "Imports", package = deps, version = "*"))
+    d$write("DESCRIPTION")
+  }
 }
 
 install_dependencies <- function(required_pkgs, ...) {
 
+  reset_repos <- use_bioc_repos()
+  on.exit(reset_repos(), add = TRUE)
+
   create_description(required_pkgs)
-  on.exit(file.remove("DESCRIPTION"))
+  on.exit(file.remove("DESCRIPTION"), add = TRUE)
   remotes::install_deps(dependencies = TRUE, ...)
 
   if (require("knitr") && packageVersion("knitr") < '1.9.19') {

bin/dependencies.R

@@ -8,8 +8,10 @@
 import re
 from argparse import ArgumentParser
 
-from util import (Reporter, read_markdown, load_yaml, check_unwanted_files,
-                  require)
+# This uses the `__all__` list in `util.py` to determine what objects to import 
+# see https://docs.python.org/3/tutorial/modules.html#importing-from-a-package
+from util import *
+from reporter import Reporter
 
 __version__ = '0.3'
 

bin/lesson_check.py

@@ -9,7 +9,8 @@
 import re
 from argparse import ArgumentParser
 
-from util import Reporter, require
+from util import require
+from reporter import Reporter
 
 # Import this way to produce a more useful error message.
 try:

bin/repo_check.py

@@ -0,0 +1,75 @@
+import sys
+
+class Reporter:
+    """Collect and report errors."""
+
+    # Marker to show that an expected value hasn't been provided.
+    # (Can't use 'None' because that might be a legitimate value.)
+    _DEFAULT_REPORTER = []
+
+    def __init__(self):
+        """Constructor."""
+        self.messages = []
+
+    def check_field(self, filename, name, values, key, expected=_DEFAULT_REPORTER):
+        """Check that a dictionary has an expected value."""
+
+        if key not in values:
+            self.add(filename, '{0} does not contain {1}', name, key)
+        elif expected is self._DEFAULT_REPORTER:
+            pass
+        elif type(expected) in (tuple, set, list):
+            if values[key] not in expected:
+                self.add(
+                    filename, '{0} {1} value {2} is not in {3}', name, key, values[key], expected)
+        elif values[key] != expected:
+            self.add(filename, '{0} {1} is {2} not {3}',
+                     name, key, values[key], expected)
+
+    def check(self, condition, location, fmt, *args):
+        """Append error if condition not met."""
+
+        if not condition:
+            self.add(location, fmt, *args)
+
+    def add(self, location, fmt, *args):
+        """Append error unilaterally."""
+
+        self.messages.append((location, fmt.format(*args)))
+
+    @staticmethod
+    def pretty(item):
+        location, message = item
+        if isinstance(location, type(None)):
+            return message
+        elif isinstance(location, str):
+            return location + ': ' + message
+        elif isinstance(location, tuple):
+            return '{0}:{1}: '.format(*location) + message
+
+        print('Unknown item "{0}"'.format(item), file=sys.stderr)
+        return NotImplemented
+
+    @staticmethod
+    def key(item):
+        location, message = item
+        if isinstance(location, type(None)):
+            return ('', -1, message)
+        elif isinstance(location, str):
+            return (location, -1, message)
+        elif isinstance(location, tuple):
+            return (location[0], location[1], message)
+
+        print('Unknown item "{0}"'.format(item), file=sys.stderr)
+        return NotImplemented
+
+    def report(self, stream=sys.stdout):
+        """Report all messages in order."""
+
+        if not self.messages:
+            return
+
+        for m in sorted(self.messages, key=self.key):
+            print(self.pretty(m), file=stream)
+
+

bin/reporter.py

@@ -1,12 +1,12 @@
 import unittest
 
 import lesson_check
-import util
+import reporter
 
 
 class TestFileList(unittest.TestCase):
     def setUp(self):
-        self.reporter = util.Reporter()  # TODO: refactor reporter class.
+        self.reporter = reporter.Reporter()  # TODO: refactor reporter class.
 
     def test_file_list_has_expected_entries(self):
         # For first pass, simply assume that all required files are present