Merge pull request #204 from gardenlinux/fix/add-virtualenv-info

Docs: Add virtualenv info to working locally guide

Author: ByteOtter

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help run build preview publish transform aggregate aggregate-repo aggregate-update-repo aggregate-repo-single aggregate-update-repo-single test-aggregate-local clean clean-projects clean-aggregated-git test test-unit test-integration check spelling linkcheck woke glossary glossary-check format
+.PHONY: help run build preview publish transform aggregate aggregate-repo aggregate-update-repo aggregate-repo-single aggregate-update-repo-single test-aggregate-local clean clean-projects clean-aggregated-git test test-unit test-integration check spelling linkcheck woke glossary glossary-check format check-system-deps
 
 help:
 	@echo "Garden Linux Documentation Hub - Available targets:"
@@ -36,7 +36,12 @@ help:
 	@echo "    clean                  - Clean aggregated docs and build artifacts"
 	@echo ""
 
-install:
+check-system-deps:
+	@if ! command -v pnpm >/dev/null 2>&1; then @echo "pnpm not found! Please install using your package manager."; exit 1; fi
+	@if ! command -v python3 --version >/dev/null 2>&1; then @echo "python3 not installed! Please install using your package manager."; exit 1; fi
+	@if ! command -v git --version >/dev/null 2>&1; then @echo "git not installed! Please install using you package manager."; exit 1; fi
+
+install: check-system-deps
 	@echo "Installing dependencies..."
 	pnpm install
 	pip install -r requirements.txt
@@ -98,7 +103,7 @@ aggregate-update-repo-single:
 		$(if $(REF),--override-ref $(REF)) \
 		$(if $(COMMIT),--override-commit $(COMMIT))
 
-run:
+run: check-system-deps
 	pnpm run docs:dev
 
 build: install clean aggregate

docs/contributing/documentation/working-locally.md

@@ -23,14 +23,15 @@ repositories into a unified documentation site.
 
 ## Working with the Documentation System Locally
 
-For more substantial changes — like adding new pages, restructuring content, or
-working on the aggregation system itself — you'll want to set up the
+For more substantial changes, (adding new pages, restructuring content, or
+working on the aggregation system itself) you will want to set up the
 documentation system locally.
 
 ### Prerequisites
 
 - Python 3.x
 - pnpm (for VitePress)
+- virtualenv (optional)
 - Git
 
 ### Step 1: Clone the Repository
@@ -49,6 +50,32 @@ pnpm install
 This installs VitePress and other Node.js dependencies needed to build the
 documentation site.
 
+:::tip Problems with installing Python Dependencies?
+
+Potentially, your Linux distribution or other operating system might forbid you from installing
+python dependencies system wide.
+
+To go around this, it is wise practice to use a [virtual environment](https://www.w3schools.com/python/python_virtualenv.asp).
+
+We use [`virtualenv`](https://virtualenv.pypa.io/en/latest/). Install virtualenv via your distributions package manager
+or a method appropriate for your operating system.
+
+Then, create the virtual environment and activate it.
+
+```bash
+virtualenv .venv && source .venv/bin/activate
+```
+
+afterwards, continue working like normal.
+
+In the end, you can deactivate the environment using
+
+```bash
+deactivate
+```
+or closing the Terminal.
+:::
+
 ### Step 3: Aggregate Documentation
 
 #### From Remote Repositories (Production)
@@ -62,7 +89,7 @@ make aggregate
 This fetches documentation from the configured repositories at their locked
 commit hashes.
 
-#### GitHub API token
+:::info Add A GitHub API Token To Counter Rate Limiting
 
 `make aggregate` also fetches every release from `gardenlinux/gardenlinux` via
 the GitHub Releases API to generate per-release note pages and to validate
@@ -74,6 +101,11 @@ export GITHUB_TOKEN=$(gh auth token)
 make aggregate
 ```
 
+:::tip
+You can add the `export` statement to you Shell's configuration file to avoid having to re-export it in different sessions.
+
+:::
+
 #### From Local Repositories (Development)
 
 For local development, use `repos-config.local.json` with `file://` URLs: