From 5d707a6bfba7926a4daf63988a3ab3c612bc3c61 Mon Sep 17 00:00:00 2001 From: cmckee786 Date: Thu, 22 Jan 2026 11:17:40 -0500 Subject: [PATCH 1/2] fix: local build weasyprint logic, dev script fixes - updated local build: checks whether weasyprint is installed on local host, currently a stop gap, TODO: add install logic per major distribution? - updated development.md with proper dependency req's - fix python virtual env to build intended directory --- docs/development.md | 30 +++++++++++++++++++----------- scripts/local-build | 44 ++++++++++++++++++++++++++++---------------- 2 files changed, 47 insertions(+), 27 deletions(-) diff --git a/docs/development.md b/docs/development.md index c03a2a1..02bf5f8 100644 --- a/docs/development.md +++ b/docs/development.md @@ -80,7 +80,7 @@ can utilize a virtual python environment with the required dependencies. - `httpd` or `apache2` - `git` - `weasyprint` - - Python 3.13+ + - Python 3.9+ - Python virtual environment with `mkdoc-material` required pip packages - a clone of the [ProLUG course-books repository](https://github.com/ProfessionalLinuxUsersGroup/course-books) @@ -103,32 +103,40 @@ source files, and deploy the website either via `httpd/apache2` or served via th Outside of system packages all files will be localized to the `/root/course-books` directory on the container or machine. +Tested on: +Rocky 10.1 LXC (550MB of packages after install) +Ubuntu 25.04 LXC (850MB of packages after install) + === "APT" - ```bash linenums="1" + ```bash linenums="1" title="install.sh" #!/bin/bash - apt-get update && apt-get -y install git python3.13-full hostname apache2 weasyprint + apt-get update && apt-get -y install git python3-full hostname apache2 weasyprint git clone https://github.com/ProfessionalLinuxUsersGroup/course-books cd course-books - python3.13 -m venv "$PWD" + python3 -m venv venv source venv/bin/activate pip install -U pip pip install -U mkdocs mkdocs-material mkdocs-glightbox mkdocs-to-pdf - # use mkdocs serve -a "$(hostname -I | awk '{print $1}'):8000" for live reloading after changes - mkdocs build -d /var/www/html/ && systemctl enable --now apache2 + # use for live reloading after changes: + # mkdocs serve -a "$(hostname -I | awk '{print $1}'):8000" + # use for local webserver: + # mkdocs build -d /var/www/html/ && systemctl enable --now apache2 ``` === "DNF" - ```bash linenums="1" + ```bash linenums="1" title="install.sh" #!/bin/bash - dnf install -y httpd git python3.13 hostname httpd weasyprint + dnf install -y git python3 python-pip pango hostname httpd weasyprint git clone https://github.com/ProfessionalLinuxUsersGroup/course-books cd course-books - python3.13 -m venv "$PWD" + python3 -m venv venv source venv/bin/activate pip install -U pip pip install -U mkdocs mkdocs-material mkdocs-glightbox mkdocs-to-pdf - # use mkdocs serve -a "$(hostname -I | awk '{print $1}'):8000" for live reloading after changes - mkdocs build -d /var/www/html/ && systemctl enable --now httpd + # use for live reloading after changes: + # mkdocs serve -a "$(hostname -I | awk '{print $1}'):8000" + # use for local webserver: + # mkdocs build -d /var/www/html/ && systemctl enable --now httpd ``` The ProLUG Linux Course Books website should now be available from your web browser either at diff --git a/scripts/local-build b/scripts/local-build index 3a9cd10..f71636b 100755 --- a/scripts/local-build +++ b/scripts/local-build @@ -23,21 +23,23 @@ # #=============================================================================== -printf "Setting up a local build for ProLUG MkDocs course books...\n" - declare -i REMOVE_VENV=0 declare -a PIP_DEPS=( "mkdocs" + "mkdocs-to-pdf" "mkdocs-material" "mkdocs-glightbox" ) cleanup() { - [[ $REMOVE_VENV -gt 0 && -d ./venv ]] && + if [[ $REMOVE_VENV -gt 0 && -d ./venv ]]; then rm -rf ./venv && printf "[INFO]: Removed virtual environment.\n" + elif [[ ! -d ./venv ]]; then + printf "[INFO]: Virtual environment not detected, no operations executed\n" + fi } -trap 'printf "Cleaning up...\n"; cleanup; exit 0;' EXIT +trap 'cleanup; exit 0;' EXIT trap 'exit 130' SIGINT trap 'exit 129' SIGHUP trap 'exit 143' SIGTERM @@ -81,7 +83,6 @@ fi while [[ -n $1 && $1 =~ ^- && ! $1 == '--' ]]; do case $1 in -rm|--remove-venv) - printf "[INFO]: Virtual environment will be removed on exit.\n" REMOVE_VENV=1 shift; ;; @@ -98,8 +99,18 @@ while [[ -n $1 && $1 =~ ^- && ! $1 == '--' ]]; do done [[ $1 == '--' ]] && shift; + setup-venv(){ - printf "Attempting to set up virtual environment...\n" + printf "[INFO]: Setting up a local build for the ProLUG MkDocs course books...\n" + printf "[INFO]: Attempting to set up virtual environment...\n" + + which weasyprint >/dev/null 2>&1 || { + printf >&2 "[ERROR]: The mkdocs-to-pdf plugin requires the 'weasyprint' package to build properly\n" + printf "[INFO]: Weasyprint has OS specific dependencies and cannot be installed via pip\n" + printf "[INFO]: Weasyprint documentation: https://doc.courtbouillon.org/weasyprint/stable/first_steps.html#installation\n" + exit 1 + } + if ! [[ -d ./venv ]]; then python3 -m venv venv || { printf >&2 "[ERROR]: Failed to set up Python virtual environment.\n\n" @@ -117,12 +128,11 @@ setup-venv(){ printf "[INFO]: Python virtual environment successfully activated.\n" - printf "[INFO]: Installing dependencies...\n" + printf "[INFO]: Attempting to install dependencies...\n" pip install -U "${PIP_DEPS[@]}" > /dev/null || { printf >&2 "[ERROR]: Failed to install dependencies!\n" return 1 } - printf "[INFO]: Dependencies successfully installed.\n" printf "[INFO]: Virtual environment setup complete.\n" return 0 } @@ -141,13 +151,15 @@ serve-mkdocs(){ return 0 } -setup-venv || { - printf >&2 "[ERROR]: Failed to set up python virtual environment!\n" - exit 1 -} +if [[ $REMOVE_VENV -eq 0 ]]; then + setup-venv || { + printf >&2 "[ERROR]: Failed to set up python virtual environment!\n" + exit 1 + } + serve-mkdocs || { + printf >&2 "[ERROR]: Ran into a problem when building/serving mkdocs site.\n" + exit 1 + } +fi -serve-mkdocs || { - printf >&2 "[ERROR]: Ran into a problem when building/serving mkdocs site.\n" - exit 1 -} exit 0 From bd2953d2c3d5a0af35bff113e84f85cfc235516d Mon Sep 17 00:00:00 2001 From: cmckee786 Date: Sat, 24 Jan 2026 12:30:23 -0500 Subject: [PATCH 2/2] fix: clarification --- scripts/local-build | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/local-build b/scripts/local-build index f71636b..7680750 100755 --- a/scripts/local-build +++ b/scripts/local-build @@ -106,7 +106,7 @@ setup-venv(){ which weasyprint >/dev/null 2>&1 || { printf >&2 "[ERROR]: The mkdocs-to-pdf plugin requires the 'weasyprint' package to build properly\n" - printf "[INFO]: Weasyprint has OS specific dependencies and cannot be installed via pip\n" + printf "[INFO]: Weasyprint has OS specific dependencies and cannot be easily installed via pip\n" printf "[INFO]: Weasyprint documentation: https://doc.courtbouillon.org/weasyprint/stable/first_steps.html#installation\n" exit 1 }