diff --git a/Makefile b/Makefile index d0bcf9eb..996b4f1a 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,5 @@ .PHONY: default check-archive check-tutorial check clean tidy \ - exercises rebuild tutorial + exercises rebuild tutorial setup-env MAKEFILE_DIR:=$(dir $(realpath $(lastword $(MAKEFILE_LIST)))) @@ -202,13 +202,16 @@ _temp/consistent/% : % ############################################################################## # Tutorial document +setup-env: + scripts/setup_env.sh + # BCP: Added the --quiet flag to suppress a bunch of INFO messages # that the macros plugin was generating on every compile -tutorial: rebuild - mkdocs build --strict --quiet +tutorial: rebuild setup-env + . .venv/bin/activate && mkdocs build --strict --quiet -serve: rebuild - mkdocs serve --quiet +serve: rebuild setup-env + . .venv/bin/activate && mkdocs serve --quiet rebuild: exercises docs/exercises.zip mkdocs.yml $(shell find docs -type f) diff --git a/README.md b/README.md index 45f41fee..fe160042 100644 --- a/README.md +++ b/README.md @@ -19,15 +19,27 @@ The CN tutorial is built using [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/). Dependencies: -* python 3.x -* pip +* python >=3.10 -```bash -# Install Material for MkDocs -pip install mkdocs-material mkdocs-macros-plugin +A suitable Python virtual environment can be created by running: + +```console +> scripts/setup_env.sh +``` + +This script only needs to be run once. + +It will create a `.venv/` with the dependencies necessary to build the CN +tutorial, which can be activated with: -# Build the tutorial -make +```console +> source .venv/bin/activate +``` + +From here, building the tutorial is straightforward: + +```console +> make ``` If you are _developing_ tutorial documentation, you may wish to include @@ -40,6 +52,9 @@ unimportant, so the empty string will suffice): TUTORIAL_TODOS= make ``` +Running `deactivate` will "turn off" the virtual environment; it can be +reactivated any time using the above `source .venv/bin/activate` command. + ### Hosting locally You can start a local server that automatically renders changes to the tutorial diff --git a/scripts/requirements.txt b/scripts/requirements.txt new file mode 100644 index 00000000..bba465d8 --- /dev/null +++ b/scripts/requirements.txt @@ -0,0 +1,2 @@ +mkdocs-material +mkdocs-macros-plugin diff --git a/scripts/setup_env.sh b/scripts/setup_env.sh new file mode 100755 index 00000000..49b7cf48 --- /dev/null +++ b/scripts/setup_env.sh @@ -0,0 +1,47 @@ +#!/bin/sh + +REQUIREMENTS="$(dirname $0)/requirements.txt" + +echo "Checking for python3..." +if ! [ -x "$(command -v python3)" ]; +then + echo "Error: python3 is not installed." >&2 + return 1 +fi + +if [ -d ".venv" ]; +then + echo "Found a '.venv' directory." + + if ! [ -e .venv/bin/activate ] + then + echo -e "\033[1;33mWARNING:\033[0m '.venv/bin/activate' not found." + echo "Running python3 -m venv .venv to repair..." + python3 -m venv .venv + fi + + # We want to check _the virtual environment's_ pip list, so activate here. + . .venv/bin/activate + + if pip freeze -r "${REQUIREMENTS}" 2>&1 | grep -q "not installed" + then + echo -e "\033[1;33mWARNING:\033[0m 'requirements.txt' not satisfied." + echo "Installing dependencies..." + pip install -qr "${REQUIREMENTS}" + fi + + echo -e "\033[1;32mEnvironment updated successfully!\033[0m" + exit +fi + +echo "No '.venv' directory found." +echo "Running python3 -m venv .venv..." +python3 -m venv .venv + +. .venv/bin/activate + +echo "Installing dependencies..." +pip install -qr "${REQUIREMENTS}" + +echo -e "\033[1;32mEnvironment created successfully!\033[0m" +echo -e "\033[1;32mActivate it with 'source .venv/bin/activate'.\033[0m"