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 diff --git a/docs/contributing/documentation/working-locally.md b/docs/contributing/documentation/working-locally.md index 7bf2050..373a33f 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: