Skip to content

Commit

Permalink
Merge pull request #28 from hpc-carpentry/new-preview-mechanism
Browse files Browse the repository at this point in the history 
suggesting a new preview mechanism
  • Loading branch information
@tkphd
tkphd authored Nov 20, 2024
2 parents 2f919b9 + 67b66e8 commit 0f86bde
Show file tree
Hide file tree
Showing 3 changed files with 24 additions and 167 deletions.
174 changes: 14 additions & 160 deletions Makefile
View file
Original file line number Diff line number Diff line change
@@ -1,166 +1,20 @@
# Use /bin/bash instead of /bin/sh
export SHELL = /bin/bash
# Makefile to build HPC Chapel lesson locally
# Docs: <https://carpentries.github.io/sandpaper-docs>

## ========================================
## Commands for both workshop and lesson websites.
# Disable the browser, if none is set.
export R_BROWSER := $(or $(R_BROWSER),"false")

# 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
all: serve
.PHONY: all build check clean serve

# 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
serve: build
Rscript -e "sandpaper::serve()"

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
build:
Rscript -e "sandpaper::build_lesson()"

check:
Rscript -e "sandpaper::check_lesson()"

# 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
clean:
Rscript -e "sandpaper::reset_site()"
11 changes: 6 additions & 5 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
6 changes: 4 additions & 2 deletions site/README.md
View file
Original file line number Diff line number Diff line change
@@ -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.

0 comments on commit 0f86bde

Please sign in to comment.