From 5deca4750aa0376e6db24857c5cf6f19f9c9f431 Mon Sep 17 00:00:00 2001 From: Alex Razoumov Date: Fri, 15 Nov 2024 10:07:53 -0800 Subject: [PATCH 1/2] suggesting a new preview mechanism as requested in https://github.com/hpc-carpentry/hpc-chapel/issues/24 --- Makefile | 168 +----------------------------------------------------- README.md | 11 ++-- 2 files changed, 8 insertions(+), 171 deletions(-) diff --git a/Makefile b/Makefile index 0cb96f6..6f834ce 100644 --- a/Makefile +++ b/Makefile @@ -1,166 +1,2 @@ -# Use /bin/bash instead of /bin/sh -export SHELL = /bin/bash - -## ======================================== -## Commands for both workshop and lesson websites. - -# Settings -MAKEFILES=Makefile $(wildcard *.mk) -JEKYLL=bundle config set path '.vendor/bundle' && bundle install && 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 - -# Default target -.DEFAULT_GOAL := commands - -## I. Commands for both workshop and lesson websites -## ================================================= - -## * serve : render website and run a local server -serve : lesson-md - ${JEKYLL} serve - -## * site : build website but do not run a server -site : lesson-md - ${JEKYLL} build - -## * docker-serve : use Docker to serve the site -docker-serve : - 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 - -## * repo-check : check repository settings -repo-check : - @${PYTHON} bin/repo_check.py -s . - -## * clean : clean up junk files -clean : - @rm -rf ${DST} - @rm -rf .sass-cache - @rm -rf bin/__pycache__ - @find . -name .DS_Store -exec rm {} \; - @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 : - @rm -rf ${RMD_DST} - @rm -rf fig/rmd-* - - -## -## II. Commands specific to workshop websites -## ================================================= - -.PHONY : workshop-check - -## * workshop-check : check workshop homepage -workshop-check : - @${PYTHON} bin/workshop_check.py . - - -## -## III. Commands specific to lesson websites -## ================================================= - -.PHONY : lesson-check lesson-md lesson-files lesson-fixme - -# RMarkdown files -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. -MARKDOWN_SRC = \ - index.md \ - CODE_OF_CONDUCT.md \ - setup.md \ - $(sort $(wildcard _episodes/*.md)) \ - reference.md \ - $(sort $(wildcard _extras/*.md)) \ - LICENSE.md - -# Generated lesson files in the order they appear in the navigation menu. -HTML_DST = \ - ${DST}/index.html \ - ${DST}/conduct/index.html \ - ${DST}/setup/index.html \ - $(patsubst _episodes/%.md,${DST}/%/index.html,$(sort $(wildcard _episodes/*.md))) \ - ${DST}/reference/index.html \ - $(patsubst _extras/%.md,${DST}/%/index.html,$(sort $(wildcard _extras/*.md))) \ - ${DST}/license/index.html - -## * 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 : 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 : - @${PYTHON} bin/lesson_check.py -s . -p ${PARSER} -r _includes/links.md -l -w --permissive - -## * unittest : run unit tests on checking tools -unittest : - @${PYTHON} bin/test_lesson_check.py - -## * 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 : - @fgrep -i -n FIXME ${MARKDOWN_SRC} || true - -## -## IV. Auxililary (plumbing) commands -## ================================================= - -## * commands : show all commands. -commands : - @sed -n -e '/^##/s|^##[[:space:]]*||p' $(MAKEFILE_LIST) - -#------------------------------------------------------------------------------- -# Include extra commands if available. -#------------------------------------------------------------------------------- - --include commands.mk +serve: + Rscript -e "sandpaper::serve()" diff --git a/README.md b/README.md index c965428..d551b6e 100644 --- a/README.md +++ b/README.md @@ -66,14 +66,15 @@ branch. Obviously having to push to GitHub every time you want to view your changes to the website isn't very convenient. To preview the lesson locally, run `make -serve`. You can then view the website at `localhost:4000` in your browser. +serve`. You can then view the website at `localhost:4321` in your browser. Pages will be automatically regenerated every time you write to them. -Note that the autogenerated website lives under the `_site` directory (and -doesn't get pushed to GitHub). +This process requires the R language and three R packages -- +[sandpaper](https://carpentries.github.io/sandpaper), [pegboard](https://carpentries.github.io/pegboard), and +[varnish](https://carpentries.github.io/varnish) -- that work together with R and [pandoc](https://pandoc.org) +to manage and deploy Carpentries Lesson websites written in Markdown or R Markdown. -This process requires Ruby, Make, and Jekyll. You can find setup instructions -[here](http://swcarpentry.github.io/lesson-example/setup/). +You can find the setup instructions [here](https://carpentries.github.io/workbench). ## Example lessons From 67b66e8ac59f2bf073b4c25cca61523363c5d012 Mon Sep 17 00:00:00 2001 From: Trevor Keller Date: Wed, 20 Nov 2024 12:39:42 -0500 Subject: [PATCH 2/2] Restore auxiliary 'make' targets --- Makefile | 20 +++++++++++++++++++- site/README.md | 6 ++++-- 2 files changed, 23 insertions(+), 3 deletions(-) diff --git a/Makefile b/Makefile index 6f834ce..69beb8f 100644 --- a/Makefile +++ b/Makefile @@ -1,2 +1,20 @@ -serve: +# Makefile to build HPC Chapel lesson locally +# Docs: + +# Disable the browser, if none is set. +export R_BROWSER := $(or $(R_BROWSER),"false") + +all: serve +.PHONY: all build check clean serve + +serve: build Rscript -e "sandpaper::serve()" + +build: + Rscript -e "sandpaper::build_lesson()" + +check: + Rscript -e "sandpaper::check_lesson()" + +clean: + Rscript -e "sandpaper::reset_site()" diff --git a/site/README.md b/site/README.md index 42997e3..d08eee9 100644 --- a/site/README.md +++ b/site/README.md @@ -1,2 +1,4 @@ -This directory contains rendered lesson materials. Please do not edit files -here. +# {sandpaper}-Generated Content + +This directory contains rendered lesson materials. +Please do not edit files here.