From 13b9148e51e3dff28baf664ef27467ced319d7b4 Mon Sep 17 00:00:00 2001 From: Tiara Lena Hock Date: Tue, 20 Oct 2026 10:32:23 +0200 Subject: [PATCH 1/3] Docs: Add virtualenv info to working locally guide Signed-off-by: Tiara Lena Hock --- .../documentation/working-locally.md | 38 +++++++++++++++++-- 1 file changed, 35 insertions(+), 3 deletions(-) diff --git a/docs/contributing/documentation/working-locally.md b/docs/contributing/documentation/working-locally.md index 7bf2050..6ab8e55 100644 --- a/docs/contributing/documentation/working-locally.md +++ b/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: From 3504236e68b308fb07c2a09b47cc7066327f30c8 Mon Sep 17 00:00:00 2001 From: Tiara Lena Hock Date: Tue, 20 Oct 2026 13:30:06 +0200 Subject: [PATCH 2/3] Feat: Add new target to check for system dependencies Signed-off-by: Tiara Lena Hock --- Makefile | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/Makefile b/Makefile index d07a970..57c2d91 100644 --- a/Makefile +++ b/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 From 63a63a4549ae5b4718094df2b2dfc206c5b4778b Mon Sep 17 00:00:00 2001 From: Tiara Lena Hock Date: Tue, 20 Oct 2026 15:02:06 +0200 Subject: [PATCH 3/3] Fix: Fix formatting issue Signed-off-by: Tiara Lena Hock --- docs/contributing/documentation/working-locally.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/documentation/working-locally.md b/docs/contributing/documentation/working-locally.md index 6ab8e55..373a33f 100644 --- a/docs/contributing/documentation/working-locally.md +++ b/docs/contributing/documentation/working-locally.md @@ -103,7 +103,7 @@ 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)