Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

suggesting a new preview mechanism #28

Merged
merged 2 commits into from
Nov 20, 2024
Merged

suggesting a new preview mechanism #28

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5deca47
suggesting a new preview mechanism as requested in https://github.com…
Nov 15, 2024
67b66e8
Restore auxiliary 'make' targets
tkphd Nov 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
174 changes: 14 additions & 160 deletions Makefile
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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.
Loading