From 8b5457db0a50d401266eead4825c3789587f8ac3 Mon Sep 17 00:00:00 2001 From: Toby Hodges Date: Tue, 18 Apr 2023 07:25:26 +0200 Subject: [PATCH] Update to final version of styles lesson template (#352) Update a very large set of changes to the template on this repository: not been updated since 2018. --- .editorconfig | 1 + .github/PULL_REQUEST_TEMPLATE.md | 2 +- .github/workflows/template.yml | 185 ++++++++++++++++ .github/workflows/website.yml | 123 +++++++++++ .gitignore | 1 + 404.md | 25 +++ CODE_OF_CONDUCT.md | 3 +- Gemfile | 8 +- LICENSE.md | 20 +- Makefile | 77 +++++-- _includes/base_path.html | 54 +++-- _includes/check_transition_variables.html | 22 ++ _includes/javascript.html | 53 ++++- _includes/lesson_footer.html | 17 +- _includes/life_cycle.html | 61 +++++- _includes/links.md | 2 +- _includes/manual_episode_order.html | 2 +- _includes/navbar.html | 22 +- _includes/syllabus.html | 19 ++ _layouts/base.html | 5 +- aio.md | 4 +- assets/css/katex.min.css | 1 + assets/css/lesson.scss | 232 ++++++++++++++------ assets/img/carpentrieslab.svg | 249 ++++++++++++++++++++++ assets/js/anchor.min.js | 9 + assets/js/katex-auto-render.min.js | 1 + assets/js/katex.min.js | 1 + bin/boilerplate/.travis.yml | 57 ----- bin/boilerplate/CONTRIBUTING.md | 16 +- bin/boilerplate/_config.yml | 28 ++- bin/dependencies.R | 107 ++++++++++ bin/generate_md_episodes.R | 33 +-- bin/install_r_deps.sh | 1 + bin/lesson_check.py | 132 +++++++++--- bin/lesson_initialize.py | 1 - bin/markdown_ast.rb | 10 +- bin/repo_check.py | 3 +- bin/reporter.py | 75 +++++++ bin/test_lesson_check.py | 4 +- bin/util.py | 107 ++-------- bin/workshop_check.py | 5 +- 41 files changed, 1391 insertions(+), 387 deletions(-) create mode 100644 .github/workflows/template.yml create mode 100644 .github/workflows/website.yml create mode 100644 404.md create mode 100644 _includes/check_transition_variables.html create mode 100644 assets/css/katex.min.css create mode 100644 assets/img/carpentrieslab.svg create mode 100644 assets/js/anchor.min.js create mode 100644 assets/js/katex-auto-render.min.js create mode 100644 assets/js/katex.min.js delete mode 100644 bin/boilerplate/.travis.yml create mode 100644 bin/dependencies.R create mode 100755 bin/install_r_deps.sh create mode 100644 bin/reporter.py diff --git a/.editorconfig b/.editorconfig index 1d7d564d..5bf4860b 100644 --- a/.editorconfig +++ b/.editorconfig @@ -9,6 +9,7 @@ trim_trailing_whitespace = true indent_size = 2 indent_style = space max_line_length = 100 # Please keep this in sync with bin/lesson_check.py! +trim_trailing_whitespace = false # keep trailing spaces in markdown - 2+ spaces are translated to a hard break (
) [*.r] max_line_length = 80 diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 07aadca2..d3368998 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.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 diff --git a/.github/workflows/template.yml b/.github/workflows/template.yml new file mode 100644 index 00000000..0665e0cf --- /dev/null +++ b/.github/workflows/template.yml @@ -0,0 +1,185 @@ +name: Test template +on: + push: + branches: gh-pages + pull_request: +jobs: + check-template: + 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: Linux + - os: macos-latest + os-name: macOS + - os: windows-latest + os-name: Windows + - lesson: swcarpentry/shell-novice + lesson-name: (SWC) Shell novice + - lesson: datacarpentry/r-intro-geospatial + 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 + env: + RSPM: 'https://packagemanager.rstudio.com/cran/__linux__/focal/latest' + steps: + - name: Set up Ruby + uses: ruby/setup-ruby@v1 + with: + ruby-version: '2.7' + bundler-cache: true + + - name: Set up Python + uses: actions/setup-python@v2 + with: + python-version: '3.x' + + - name: Install GitHub Pages, Bundler, and kramdown gems + run: | + gem install github-pages bundler kramdown kramdown-parser-gfm + + - name: Install Python modules + run: | + if [[ $RUNNER_OS == macOS || $RUNNER_OS == Linux ]]; then + python3 -m pip install --upgrade pip setuptools wheel pyyaml==5.3.1 requests + elif [[ $RUNNER_OS == Windows ]]; then + python -m pip install --upgrade pip setuptools wheel pyyaml==5.3.1 requests + fi + + - name: Checkout the ${{ matrix.lesson }} lesson + uses: actions/checkout@master + with: + repository: ${{ matrix.lesson }} + path: lesson + fetch-depth: 0 + + - name: Sync lesson with carpentries/styles + working-directory: lesson + run: | + echo "::group::Fetch Styles" + if [[ -n "${{ github.event.pull_request.number }}" ]] + then + ref="refs/pull/${{ github.event.pull_request.number }}/head" + else + ref="gh-pages" + fi + + git config --global user.email "team@carpentries.org" + git config --global user.name "The Carpentries Bot" + + git remote add styles https://github.com/carpentries/styles.git + 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 + working-directory: lesson + run: | + echo "count=$(shopt -s nullglob; files=($(find . -iname '*.Rmd')); echo ${#files[@]})" >> $GITHUB_OUTPUT + + - name: Set up R + if: steps.check-rmd.outputs.count != 0 + uses: r-lib/actions/setup-r@v2 + with: + use-public-rspm: true + install-r: false + + - name: Install needed packages + if: steps.check-rmd.outputs.count != 0 + working-directory: lesson + run: | + source('bin/dependencies.R') + install_required_packages(.libPaths()[1]) + shell: Rscript {0} + + - name: Query dependencies + if: steps.check-rmd.outputs.count != 0 + working-directory: lesson + run: | + 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: Restore Package Cache + if: runner.os != 'Windows' && steps.check-rmd.outputs.count != 0 + uses: actions/cache@v2 + with: + path: ${{ env.R_LIBS_USER }} + key: ${{ runner.os }}-${{ hashFiles('.github/R-version') }}-1-${{ hashFiles('.github/depends.Rds') }} + restore-keys: ${{ runner.os }}-${{ hashFiles('.github/R-version') }}-1- + + - name: Install stringi from source + if: runner.os == 'Linux' && steps.check-rmd.outputs.count != 0 + run: install.packages('stringi', repos='https://cloud.r-project.org') + shell: Rscript {0} + + - name: Install system dependencies for R packages + if: runner.os == 'Linux' && steps.check-rmd.outputs.count != 0 + working-directory: lesson + run: | + while read -r cmd + do + 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 diff --git a/.github/workflows/website.yml b/.github/workflows/website.yml new file mode 100644 index 00000000..be0b1875 --- /dev/null +++ b/.github/workflows/website.yml @@ -0,0 +1,123 @@ +name: Website +on: + push: + branches: + - gh-pages + - main + pull_request: [] +jobs: + build-website: + if: ${{ !endsWith(github.repository, '/styles') }} + runs-on: ubuntu-20.04 + env: + RSPM: "https://packagemanager.rstudio.com/cran/__linux__/focal/latest" + GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} + defaults: + run: + shell: bash + steps: + - name: Set up Ruby + uses: ruby/setup-ruby@v1 + with: + ruby-version: '2.7' + bundler-cache: true + + - name: Set up Python + uses: actions/setup-python@v2 + with: + python-version: '3.x' + + - name: Install GitHub Pages, Bundler, and kramdown gems + run: | + gem install github-pages bundler kramdown kramdown-parser-gfm + + - name: Install Python modules + run: | + python3 -m pip install --upgrade pip setuptools wheel pyyaml==5.3.1 requests + + - name: Checkout the lesson + uses: actions/checkout@master + with: + fetch-depth: 0 + ref: ${{ github.event.pull_request.head.sha }} + + - name: Look for R-markdown files + id: check-rmd + run: | + echo "count=$(shopt -s nullglob; files=($(find . -iname '*.Rmd')); echo ${#files[@]})" >> $GITHUB_OUTPUT + + - name: Set up R + if: steps.check-rmd.outputs.count != 0 + uses: r-lib/actions/setup-r@v2 + with: + use-public-rspm: true + install-r: false + + - name: Restore R Cache + if: steps.check-rmd.outputs.count != 0 + uses: actions/cache@v2 + with: + path: ${{ env.R_LIBS_USER }} + key: ${{ runner.os }}-${{ hashFiles('.github/R-version') }}-1-${{ hashFiles('.github/depends.Rds') }} + restore-keys: ${{ runner.os }}-${{ hashFiles('.github/R-version') }}-1- + + - name: Install needed packages + if: steps.check-rmd.outputs.count != 0 + run: | + source('bin/dependencies.R') + install_required_packages() + shell: Rscript {0} + + - name: Query dependencies + if: steps.check-rmd.outputs.count != 0 + run: | + 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: Install system dependencies for R packages + if: steps.check-rmd.outputs.count != 0 + run: | + while read -r cmd + do + 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 + run: make site + + - name: Checkout github pages + if: ${{ github.event_name == 'push' && steps.check-rmd.outputs.count != 0 && github.ref != 'refs/heads/gh-pages'}} + uses: actions/checkout@master + with: + ref: gh-pages + path: gh-pages + + - name: Commit and Push + if: ${{ github.event_name == 'push' && steps.check-rmd.outputs.count != 0 && github.ref != 'refs/heads/gh-pages'}} + run: | + # clean up gh-pages + cd gh-pages + git rm -rf . # remove all previous files + git restore --staged . # remove things from the stage + cd .. + # copy everything into gh-pages site + cp -r `ls -A | grep -v 'gh-pages' | grep -v '.git' | grep -v '.bundle/' | grep -v '_site'` gh-pages + # move into gh-pages, add, commit, and push + cd gh-pages + # setup git + git config --local user.email "actions@github.com" + git config --local user.name "GitHub Actions" + git add -A . + git commit --allow-empty -m "[Github Actions] render website (via ${{ github.sha }})" + git push origin gh-pages + # return + cd .. + + - run: make lesson-check-all + if: always() diff --git a/.gitignore b/.gitignore index 98325e86..b1d448b5 100644 --- a/.gitignore +++ b/.gitignore @@ -5,6 +5,7 @@ .ipynb_checkpoints .sass-cache .jekyll-cache/ +.jekyll-metadata __pycache__ _site .Rproj.user diff --git a/404.md b/404.md new file mode 100644 index 00000000..c1cf9dd4 --- /dev/null +++ b/404.md @@ -0,0 +1,25 @@ +--- +layout: base +root: . +permalink: 404.html +title: "Page not found" +--- + +# Oops! We cannot find that page. +{: style="text-align: center;"} + +> ## Our apologies! +> +> We cannot seem to find the page you are looking for. +> Try going back to the previous page or +> navigate to any other page using the navigation bar above +> {%- if site.kind == "lesson" -%} or the schedule below {%- endif -%}. +> If you got here by clicking on a link in the +> {%- if site.kind == "lesson" -%} lesson {%- else -%} workshop {%- endif -%}, +> please report this link to the +> {%- if site.kind == "lesson" -%} lesson developers {%- else -%} workshop organizers {%- endif -%}. +{: .caution} + +{% if site.kind == "lesson" %} + {% include syllabus.html %} +{% endif%} diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index c3b96690..2cf1133b 100644 --- a/CODE_OF_CONDUCT.md +++ b/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 diff --git a/Gemfile b/Gemfile index fb25ae48..8d69492b 100644 --- a/Gemfile +++ b/Gemfile @@ -2,9 +2,13 @@ source 'https://rubygems.org' -git_source(:github) {|repo_name| "https://github.com/#{repo_name}" } +git_source(:github) { |repo_name| "https://github.com/#{repo_name}" } # Synchronize with https://pages.github.com/versions -ruby '>=2.5.8' +ruby '>=2.7.1' gem 'github-pages', group: :jekyll_plugins + +if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('3.0.0') + gem 'webrick', '>= 1.6.1' +end \ No newline at end of file diff --git a/LICENSE.md b/LICENSE.md index 79b88169..2736a2ec 100644 --- a/LICENSE.md +++ b/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 diff --git a/Makefile b/Makefile index b585662c..6bf02c6d 100644 --- a/Makefile +++ b/Makefile @@ -3,16 +3,19 @@ # Settings MAKEFILES=Makefile $(wildcard *.mk) -JEKYLL=bundle config --local set path .vendor/bundle && bundle install && bundle update && bundle exec jekyll +JEKYLL=bundle config set --local path .vendor/bundle && bundle install && bundle update && bundle exec jekyll 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) ifneq (, $(PYTHON3_EXE)) ifeq (,$(findstring Microsoft/WindowsApps/python3,$(subst \,/,$(PYTHON3_EXE)))) - PYTHON := python3 + PYTHON := $(PYTHON3_EXE) endif endif @@ -21,46 +24,50 @@ ifeq (,$(PYTHON)) 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.") + ifeq (3, ${PYTHON_VERSION_MAJOR}) + PYTHON := $(PYTHON_EXE) + else + PYTHON_NOTE = "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.") + PYTHON_NOTE = "Your system does not appear to have any Python installed." endif endif -# Controls -.PHONY : commands clean files - # Default target .DEFAULT_GOAL := commands ## I. Commands for both workshop and lesson websites ## ================================================= +.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 : +repo-check : python @${PYTHON} bin/repo_check.py -s . ## * clean : clean up junk files @@ -68,6 +75,9 @@ clean : @rm -rf ${DST} @rm -rf .sass-cache @rm -rf bin/__pycache__ + @rm -rf .vendor + @rm -rf .bundle + @rm -f Gemfile.lock @find . -name .DS_Store -exec rm {} \; @find . -name '*~' -exec rm {} \; @find . -name '*.pyc' -exec rm {} \; @@ -85,7 +95,7 @@ clean-rmd : .PHONY : workshop-check ## * workshop-check : check workshop homepage -workshop-check : +workshop-check : python @${PYTHON} bin/workshop_check.py . @@ -93,10 +103,10 @@ workshop-check : ## III. Commands specific to lesson websites ## ================================================= -.PHONY : lesson-check lesson-md lesson-files lesson-fixme +.PHONY : lesson-check lesson-md lesson-files lesson-fixme install-rmd-deps # RMarkdown files -RMD_SRC = $(wildcard _episodes_rmd/??-*.Rmd) +RMD_SRC = $(wildcard _episodes_rmd/*.Rmd) RMD_DST = $(patsubst _episodes_rmd/%.Rmd,_episodes/%.md,$(RMD_SRC)) # Lesson source files in the order they appear in the navigation menu. @@ -115,26 +125,31 @@ HTML_DST = \ ${DST}/conduct/index.html \ ${DST}/setup/index.html \ $(patsubst _episodes/%.md,${DST}/%/index.html,$(sort $(wildcard _episodes/*.md))) \ - ${DST}/reference/index.html \ + ${DST}/reference.html \ $(patsubst _extras/%.md,${DST}/%/index.html,$(sort $(wildcard _extras/*.md))) \ ${DST}/license/index.html +## * install-rmd-deps : Install R packages dependencies to build the RMarkdown lesson +install-rmd-deps: + @${SHELL} bin/install_r_deps.sh + ## * lesson-md : convert Rmarkdown files to markdown lesson-md : ${RMD_DST} -_episodes/%.md: _episodes_rmd/%.Rmd - @bin/knit_lessons.sh $< $@ +_episodes/%.md: _episodes_rmd/%.Rmd install-rmd-deps + @mkdir -p _episodes + @$(SHELL) bin/knit_lessons.sh $< $@ ## * lesson-check : validate lesson Markdown -lesson-check : lesson-fixme +lesson-check : python lesson-fixme @${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 : +lesson-check-all : python @${PYTHON} bin/lesson_check.py -s . -p ${PARSER} -r _includes/links.md -l -w --permissive ## * unittest : run unit tests on checking tools -unittest : +unittest : python @${PYTHON} bin/test_lesson_check.py ## * lesson-files : show expected names of generated files for debugging @@ -152,6 +167,22 @@ lesson-fixme : ## IV. Auxililary (plumbing) commands ## ================================================= +.PHONY : commands python + ## * commands : show all commands. commands : @sed -n -e '/^##/s|^##[[:space:]]*||p' $(MAKEFILE_LIST) + +python : +ifeq (, $(PYTHON)) + $(error $(PYTHON_NOTE)) +else + @: +endif + +index.md : +ifeq (, $(wildcard index.md)) + $(error index.md not found) +else + @: +endif diff --git a/_includes/base_path.html b/_includes/base_path.html index 7efb3570..4f343afa 100644 --- a/_includes/base_path.html +++ b/_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 %} diff --git a/_includes/check_transition_variables.html b/_includes/check_transition_variables.html new file mode 100644 index 00000000..71d48268 --- /dev/null +++ b/_includes/check_transition_variables.html @@ -0,0 +1,22 @@ +{% assign date = include.need_transition_date %} + +{% if date == "true" %} +{% unless site.transition_date_prebeta %} +
+ you need to specify the variable transition_date_prebeta + in _config.yml. +
+{% endunless %} +{% unless site.transition_date_beta %} +
+ you need to specify the variable transition_date_beta + in _config.yml. +
+{% endunless %} +{% unless site.transition_date_prerelease %} +
+ you need to specify the variable transition_date_prerelease + in _config.yml. +
+{% endunless %} +{% endif %} diff --git a/_includes/javascript.html b/_includes/javascript.html index fcc74e6e..0832664f 100644 --- a/_includes/javascript.html +++ b/_includes/javascript.html @@ -4,11 +4,52 @@ + +{% if site.kind == "lesson" %} + + +{% endif %} + +{% if page.math %} + + + +{% 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 -%} + + + diff --git a/_includes/lesson_footer.html b/_includes/lesson_footer.html index b0eb2991..33f9e666 100644 --- a/_includes/lesson_footer.html +++ b/_includes/lesson_footer.html @@ -28,13 +28,16 @@ {% endif %}
- {% if page.source %} - {% if page.source == "Rmd" %} - Edit on GitHub - {% endif %} - {% else %} - Edit on GitHub - {% endif %} + {% if site.life_cycle == 'transition-step-2' %} + {% assign edit_url = "https://carpentries.github.io/workbench/contributor/beta.html?id=" | append: repo_url %} + {% else %} + {% assign edit_url = repo_url %} + {% endif %} + {% if page.source == "Rmd" %} + Edit on GitHub + {% else %} + Edit on GitHub + {% endif %} / Contributing / diff --git a/_includes/life_cycle.html b/_includes/life_cycle.html index efc5b6d9..bcae53e4 100644 --- a/_includes/life_cycle.html +++ b/_includes/life_cycle.html @@ -28,7 +28,66 @@ {% elsif site.life_cycle == "stable" %} {% comment %} -We don't do anything special for now +We do not do anything special for lessons in stable {% endcomment %} + +{% comment %} +Below we cover the 2 phases of lesson transition towards the Carpentries Workbench: +Variables needed: + - transition_date_prebeta: the date of the prebeta stage + - transition_date_beta: the date of the beta stage + - transition_date_prerelease: the date of the prerelease stage + +- transition-step-1: We notify that there is a snapshot of the lesson available for testing, and that it will supersede this version. +- transition-step-2 We indicate that this version of the lesson is a snapshot and a new version of the lesson is avaiable and will supersede this version at a given date. +{% endcomment %} + +{% elsif site.life_cycle == "transition-step-1" %} +{% include check_transition_variables.html need_transition_date = 'true' %} + +
+ A snapshot of this lesson from {{ site.transition_date_prebeta }} is being tested on + The Carpentries Workbench: + https://preview.carpentries.org/{{ repo_name }}. +
+ The Workbench version of this lesson will become default on {{ site.transition_date_prerelease }}. + +
+ +{% elsif site.life_cycle == "transition-step-2" %} +{% include check_transition_variables.html need_transition_date = 'true' %} + + + +{% endif %} + + + +{% comment %} +For Carpentries Lab lessons we add a banner about the review status +{% endcomment %} + +{% if site.carpentry == "lab" %} +{% if site.doi contains "zenodo" %}{% assign listing=" on Zenodo" %} +{% elsif site.doi contains "jose" %}{% assign listing=" in JOSE" %} +{% else %}{% assign listing="none" %} +{% endif %} + +
+
+ This lesson has passed peer-review! {% if site.doi != "" %}See the publication{{ listing }}.{% endif %} +
+
{% endif %} diff --git a/_includes/links.md b/_includes/links.md index abe60930..7f8e0026 100644 --- a/_includes/links.md +++ b/_includes/links.md @@ -12,7 +12,7 @@ [cran-stringr]: https://cran.r-project.org/package=stringr [dc-lessons]: http://www.datacarpentry.org/lessons/ [email]: mailto:team@carpentries.org -[github-importer]: https://import.github.com/ +[github-importer]: https://import2.github.com/ [importer]: https://github.com/new/import [jekyll-collection]: https://jekyllrb.com/docs/collections/ [jekyll-install]: https://jekyllrb.com/docs/installation/ diff --git a/_includes/manual_episode_order.html b/_includes/manual_episode_order.html index 79086271..9729ac50 100644 --- a/_includes/manual_episode_order.html +++ b/_includes/manual_episode_order.html @@ -3,7 +3,7 @@ GitHub Pages switches to Jekyll that supports it without any major hackery. Note, some logic will be required even when this transition happens - but it won't be as involved as what we have to do + but it will not be as involved as what we have to do in this file. To order lesson episodes or extras manually diff --git a/_includes/navbar.html b/_includes/navbar.html index 9db636a2..c9d2fb8e 100644 --- a/_includes/navbar.html +++ b/_includes/navbar.html @@ -32,6 +32,10 @@ + {% elsif site.carpentry == "lab" %} + + + {% endif %} {% comment %} Always show link to home page. {% endcomment %} @@ -80,7 +84,9 @@ {% else %} {% assign extra = lesson_extra %} {% endif %} -
  • {{ extra.title }}
    • + {% unless extra.exclude %} +
  • {{ extra.title }}
    • + {% endunless %} {% endfor %} @@ -88,12 +94,16 @@ {% comment %} Always show license. {% endcomment %}
  • License
    • - {% if page.source %} - {% if page.source == "Rmd" %} -
  • Improve this page
    • - {% endif %} + {% if site.life_cycle == 'transition-step-2' %} + {% assign edit_url = "https://carpentries.github.io/workbench/contributor/beta.html?id=" | append: repo_url %} + {% else %} + {% assign edit_url = repo_url %} + {% endif %} + + {% if page.source == "Rmd" %} +
  • Improve this page
    • {% else %} -
  • Improve this page
    • +
  • Improve this page
    • {% endif %}