From 6207946faa56035330fd8fc50c0fece18abc6454 Mon Sep 17 00:00:00 2001 From: Eike Waldt Date: Wed, 1 Apr 2026 11:53:16 +0200 Subject: [PATCH] feat: restructure docs-ng docs into main Diataxis structure Signed-off-by: Eike Waldt On-behalf-of: SAP --- .gitignore | 11 +- README.md | 2 +- docs/contributing/documentation/index.md | 1 + .../aggregation-architecture.md} | 22 +- .../documentation}/adding-repos.md | 17 +- .../configuration.md | 55 ++-- .../reference => documentation}/technical.md | 19 +- .../reference => documentation}/testing.md | 19 +- .../docs-ng/overview/index.md | 88 ------- .../docs-ng/tutorials/getting_started.md | 152 ----------- docs/tutorials/documentation/index.md | 236 ++++++++++++++++++ src/README.md | 2 +- tests/README.md | 2 +- 13 files changed, 310 insertions(+), 316 deletions(-) create mode 120000 docs/contributing/documentation/index.md rename docs/{reference/supporting_tools/docs-ng/explanation/architecture.md => explanation/documentation/aggregation-architecture.md} (88%) rename docs/{reference/supporting_tools/docs-ng/how-to => how-to/documentation}/adding-repos.md (86%) rename docs/reference/{supporting_tools/docs-ng/reference => documentation}/configuration.md (87%) rename docs/reference/{supporting_tools/docs-ng/reference => documentation}/technical.md (85%) rename docs/reference/{supporting_tools/docs-ng/reference => documentation}/testing.md (84%) delete mode 100644 docs/reference/supporting_tools/docs-ng/overview/index.md delete mode 100644 docs/reference/supporting_tools/docs-ng/tutorials/getting_started.md create mode 100644 docs/tutorials/documentation/index.md diff --git a/.gitignore b/.gitignore index a8304ed..ab73b32 100644 --- a/.gitignore +++ b/.gitignore @@ -15,16 +15,25 @@ docs/**/assets # Section directories - aggregated content is ignored, index.md is tracked docs/contributing/** !docs/contributing/index.md +!docs/contributing/documentation/ +!docs/contributing/documentation/** docs/explanation/** !docs/explanation/index.md +!docs/explanation/documentation/ +!docs/explanation/documentation/** docs/how-to/** +!docs/how-to/documentation/ +!docs/how-to/documentation/** !docs/how-to/index.md docs/reference/** +!docs/reference/documentation/ +!docs/reference/documentation/** !docs/reference/glossary.md !docs/reference/index.md !docs/reference/supporting_tools/ docs/reference/supporting_tools/** !docs/reference/supporting_tools/index.md -!docs/reference/supporting_tools/docs-ng/ docs/tutorials/** +!docs/tutorials/documentation/ +!docs/tutorials/documentation/** !docs/tutorials/index.md diff --git a/README.md b/README.md index d0c1cc7..5e9af15 120000 --- a/README.md +++ b/README.md @@ -1 +1 @@ -docs/reference/supporting_tools/docs-ng/overview/index.md \ No newline at end of file +docs/contributing/documentation/index.md \ No newline at end of file diff --git a/docs/contributing/documentation/index.md b/docs/contributing/documentation/index.md new file mode 120000 index 0000000..aa5f121 --- /dev/null +++ b/docs/contributing/documentation/index.md @@ -0,0 +1 @@ +../../tutorials/documentation/index.md \ No newline at end of file diff --git a/docs/reference/supporting_tools/docs-ng/explanation/architecture.md b/docs/explanation/documentation/aggregation-architecture.md similarity index 88% rename from docs/reference/supporting_tools/docs-ng/explanation/architecture.md rename to docs/explanation/documentation/aggregation-architecture.md index 5a8617b..5d775f1 100644 --- a/docs/reference/supporting_tools/docs-ng/explanation/architecture.md +++ b/docs/explanation/documentation/aggregation-architecture.md @@ -1,20 +1,17 @@ --- -title: "docs-ng Architecture" -description: "Deep dive into how the docs-ng documentation aggregation system works" -github_org: gardenlinux -github_repo: docs-ng -github_source_path: docs/reference/supporting_tools/docs-ng/explanation/architecture.md +title: "Documentation Aggregation Architecture" +description: "Deep dive into how the documentation aggregation system works" --- -# docs-ng Architecture +# Documentation Aggregation Architecture -Deep dive into the design and implementation of the docs-ng documentation aggregation system. +Deep dive into the design and implementation of the documentation aggregation system. > **Source Repository:** [gardenlinux/docs-ng](https://github.com/gardenlinux/docs-ng) ## System Overview -docs-ng is a documentation aggregation pipeline that combines content from multiple source repositories into a unified VitePress documentation site. +We use a documentation aggregation pipeline that combines content from multiple source repositories into a unified VitePress documentation site. ``` ┌─────────────────┐ @@ -282,7 +279,8 @@ Temp Directory Docs Output ## See Also -- [Technical Reference](/reference/supporting_tools/docs-ng/reference/technical) — Module and API documentation -- [Configuration Reference](/reference/supporting_tools/docs-ng/reference/configuration) — Complete configuration field reference -- [Getting Started](/reference/supporting_tools/docs-ng/tutorials/getting_started) — Setup guide -- [Adding Repositories](/reference/supporting_tools/docs-ng/how-to/adding-repos) — How to add new repos +- [Getting Started Tutorial](../../tutorials/documentation/index.md) — Step-by-step guide to contributing documentation +- [Adding Repositories](../../how-to/documentation/adding-repos.md) — How to add new repositories to the aggregation +- [Technical Reference](../../reference/documentation/technical.md) — Source code and API documentation +- [Configuration Reference](../../reference/documentation/configuration.md) — Complete configuration options +- [Architecture Explanation](../../explanation/documentation/aggregation-architecture.md) — Deep dive into how the documentation aggregation system works diff --git a/docs/reference/supporting_tools/docs-ng/how-to/adding-repos.md b/docs/how-to/documentation/adding-repos.md similarity index 86% rename from docs/reference/supporting_tools/docs-ng/how-to/adding-repos.md rename to docs/how-to/documentation/adding-repos.md index ac7357a..49c8d9b 100644 --- a/docs/reference/supporting_tools/docs-ng/how-to/adding-repos.md +++ b/docs/how-to/documentation/adding-repos.md @@ -1,14 +1,11 @@ --- -title: "How to Add Repositories to docs-ng" +title: "Adding Repositories to documentation aggregation" description: "Guide for adding new repositories to the documentation aggregation system" -github_org: gardenlinux -github_repo: docs-ng -github_source_path: docs/reference/supporting_tools/docs-ng/how-to/adding-repos.md --- -# How to Add Repositories to docs-ng +# Adding Repositories to documentation aggregation -This guide explains how to add a new repository to the docs-ng aggregation system. +This guide explains how to add a new repository to the documentation aggregation system. > **Source Repository:** [gardenlinux/docs-ng](https://github.com/gardenlinux/docs-ng) @@ -251,6 +248,8 @@ Here's a complete configuration: ## See Also -- [Configuration Reference](/reference/supporting_tools/docs-ng/reference/configuration) — Complete field documentation -- [Architecture Explanation](/reference/supporting_tools/docs-ng/explanation/architecture) — How aggregation works -- [Technical Reference](/reference/supporting_tools/docs-ng/reference/technical) — Source code documentation +- [Getting Started Tutorial](../../tutorials/documentation/index.md) — Step-by-step guide to contributing documentation +- [Adding Repositories](../../how-to/documentation/adding-repos.md) — How to add new repositories to the aggregation +- [Technical Reference](../../reference/documentation/technical.md) — Source code and API documentation +- [Configuration Reference](../../reference/documentation/configuration.md) — Complete configuration options +- [Architecture Explanation](../../explanation/documentation/aggregation-architecture.md) — Deep dive into how the documentation aggregation system works diff --git a/docs/reference/supporting_tools/docs-ng/reference/configuration.md b/docs/reference/documentation/configuration.md similarity index 87% rename from docs/reference/supporting_tools/docs-ng/reference/configuration.md rename to docs/reference/documentation/configuration.md index f3b4db2..db68859 100644 --- a/docs/reference/supporting_tools/docs-ng/reference/configuration.md +++ b/docs/reference/documentation/configuration.md @@ -1,14 +1,11 @@ --- -title: "docs-ng Configuration Reference" +title: "Documentation Aggregation Configuration Reference" description: "Complete reference for repos-config.json and repos-config.local.json configuration options" -github_org: gardenlinux -github_repo: docs-ng -github_source_path: docs/reference/supporting_tools/docs-ng/reference/configuration.md --- -# docs-ng Configuration Reference +# Documentation Aggregation Configuration Reference -Complete reference for configuring the docs-ng aggregation system. +Complete reference for configuring the documentation aggregation system. > **Source Repository:** [gardenlinux/docs-ng](https://github.com/gardenlinux/docs-ng) @@ -54,12 +51,14 @@ Development configuration file for local testing. Uses `file://` URLs to avoid g ### Required Fields #### `name` + - **Type:** String - **Description:** Unique identifier for the repository - **Example:** `"gardenlinux"`, `"builder"`, `"python-gardenlinux-lib"` - **Notes:** Used in generated paths and logging #### `url` + - **Type:** String (URL or file path) - **Description:** Repository location - **Examples:** @@ -68,18 +67,21 @@ Development configuration file for local testing. Uses `file://` URLs to avoid g - **Notes:** For local development, use `file://` URLs in `repos-config.local.json` #### `docs_path` + - **Type:** String - **Description:** Path to documentation directory within the repository - **Examples:** `"docs"`, `"documentation"`, `"."` (for root) - **Notes:** Relative to repository root; content of this directory is copied #### `target_path` + - **Type:** String - **Description:** Destination path in the docs directory - **Example:** `"projects/gardenlinux"` - **Notes:** Usually `projects/` for project mirrors #### `ref` + - **Type:** String - **Description:** Git reference to fetch (branch, tag, or commit) - **Examples:** `"main"`, `"docs-ng"`, `"v1.0.0"` @@ -88,6 +90,7 @@ Development configuration file for local testing. Uses `file://` URLs to avoid g ### Optional Fields #### `commit` + - **Type:** String (commit hash) - **Description:** Lock to a specific commit for reproducible builds - **Example:** `"abc123def456..."` @@ -95,6 +98,7 @@ Development configuration file for local testing. Uses `file://` URLs to avoid g - **Notes:** Generated automatically with `make aggregate-update` #### `root_files` + - **Type:** Array of strings - **Description:** Root-level files to copy (e.g., README.md, CONTRIBUTING.md) - **Example:** `["README.md", "CONTRIBUTING.md", "LICENSE"]` @@ -102,6 +106,7 @@ Development configuration file for local testing. Uses `file://` URLs to avoid g - **Notes:** Files can have `github_target_path` frontmatter for targeted placement #### `structure` + - **Type:** String or Object - **Description:** How to reorganize directory structure - **Options:** @@ -111,6 +116,7 @@ Development configuration file for local testing. Uses `file://` URLs to avoid g - **Default:** `"flat"` **Custom Structure Example:** + ```json "structure": { "tutorials": "tutorials", @@ -123,16 +129,18 @@ Development configuration file for local testing. Uses `file://` URLs to avoid g This maps source directories to Diataxis categories. #### `media_directories` + - **Type:** Array of strings - **Description:** Directory names to treat as media/assets - **Example:** `[".media", "assets", "_static", "images"]` - **Default:** `[]` -- **Notes:** +- **Notes:** - Searched recursively in source repository - Nested media dirs (e.g., `tutorials/assets/`) copied to same relative path - Root-level media dirs (e.g., `_static/`) copied to common ancestor of targeted files #### `special_files` + - **Type:** Object (filename → category mapping) - **Description:** Map non-standard files to Diataxis categories - **Example:** @@ -158,10 +166,7 @@ This maps source directories to Diataxis categories. "target_path": "projects/gardenlinux", "ref": "docs-ng", "commit": "c4b1d8d7f878fcb3e779315d28e35fcb19ae4dfb", - "root_files": [ - "CONTRIBUTING.md", - "SECURITY.md" - ], + "root_files": ["CONTRIBUTING.md", "SECURITY.md"], "structure": { "tutorials": "tutorials", "how-to": "how-to", @@ -169,11 +174,7 @@ This maps source directories to Diataxis categories. "reference": "reference", "contributing": "contributing" }, - "media_directories": [ - ".media", - "assets", - "_static" - ] + "media_directories": [".media", "assets", "_static"] }, { "name": "builder", @@ -183,11 +184,7 @@ This maps source directories to Diataxis categories. "ref": "docs-ng", "commit": "b10476ad8c46130f310e36daa42c6e2c14fb51a9", "structure": "flat", - "media_directories": [ - ".media", - "assets", - "_static" - ] + "media_directories": [".media", "assets", "_static"] }, { "name": "python-gardenlinux-lib", @@ -197,11 +194,7 @@ This maps source directories to Diataxis categories. "ref": "docs-ng", "commit": "9142fccc3d83ab51759db7d328fa19166bc1df63", "structure": "sphinx", - "media_directories": [ - ".media", - "assets", - "_static" - ] + "media_directories": [".media", "assets", "_static"] } ] } @@ -223,6 +216,7 @@ This maps source directories to Diataxis categories. - Keep structure and other settings consistent with production **Example local config:** + ```json { "repos": [ @@ -278,6 +272,7 @@ Repository using `github_target_path` frontmatter: ``` Then in your markdown files: + ```yaml --- title: "My Tutorial" @@ -297,7 +292,7 @@ These help create source links in the documentation. ## See Also -- [Getting Started](/reference/supporting_tools/docs-ng/tutorials/getting_started) — Initial setup guide -- [Adding Repositories](/reference/supporting_tools/docs-ng/how-to/adding-repos) — How to add new repos -- [Technical Reference](/reference/supporting_tools/docs-ng/reference/technical) — Source code documentation -- [Architecture](/reference/supporting_tools/docs-ng/explanation/architecture) — System design +- [Getting Started](../../tutorials/documentation/index.md) — Initial setup guide +- [Adding Repositories](../../how-to/documentation/adding-repos.md) — How to add new repos +- [Technical Reference](./technical.md) — Source code documentation +- [Architecture](../../explanation/documentation/aggregation-architecture.md) — System design diff --git a/docs/reference/supporting_tools/docs-ng/reference/technical.md b/docs/reference/documentation/technical.md similarity index 85% rename from docs/reference/supporting_tools/docs-ng/reference/technical.md rename to docs/reference/documentation/technical.md index ab2caf7..e930641 100644 --- a/docs/reference/supporting_tools/docs-ng/reference/technical.md +++ b/docs/reference/documentation/technical.md @@ -1,14 +1,11 @@ --- -title: "docs-ng Technical Reference" -description: "Source code documentation for the docs-ng aggregation system - modules, APIs, and implementation details" -github_org: gardenlinux -github_repo: docs-ng -github_source_path: docs/reference/supporting_tools/docs-ng/reference/technical.md +title: "Documentation Aggregation Technical Reference" +description: "Source code documentation for the documentation aggregation system - modules, APIs, and implementation details" --- -# docs-ng Technical Reference +# Documentation Aggregation Technical Reference -Source code documentation for the docs-ng aggregation system. +Source code documentation for the documentation aggregation system. > **Source Repository:** [gardenlinux/docs-ng](https://github.com/gardenlinux/docs-ng) > **Source File:** [src/README.md](https://github.com/gardenlinux/docs-ng/blob/main/src/README.md) @@ -148,7 +145,7 @@ This ensures reproducible builds. ### Running Tests -See [Testing Reference](/reference/supporting_tools/docs-ng/reference/testing) for details on the test suite. +See [Testing Reference](./testing.md) for details on the test suite. ### Adding New Transformation @@ -176,6 +173,6 @@ Key architectural decisions are documented in the source repository: ## See Also -- [Testing Reference](/reference/supporting_tools/docs-ng/reference/testing) — Test suite documentation -- [Configuration Reference](/reference/supporting_tools/docs-ng/reference/configuration) — Complete configuration field reference -- [Architecture Explanation](/reference/supporting_tools/docs-ng/explanation/architecture) — How the system works +- [Testing Reference](./testing.md) — Test suite documentation +- [Configuration Reference](./configuration.md) — Complete configuration field reference +- [Architecture Explanation](../../explanation/documentation/aggregation-architecture.md) — How the system works diff --git a/docs/reference/supporting_tools/docs-ng/reference/testing.md b/docs/reference/documentation/testing.md similarity index 84% rename from docs/reference/supporting_tools/docs-ng/reference/testing.md rename to docs/reference/documentation/testing.md index b89bd43..6a72bf4 100644 --- a/docs/reference/supporting_tools/docs-ng/reference/testing.md +++ b/docs/reference/documentation/testing.md @@ -1,14 +1,11 @@ --- -title: "docs-ng Testing Guide" -description: "Test suite documentation for docs-ng - unit tests, integration tests, and testing best practices" -github_org: gardenlinux -github_repo: docs-ng -github_source_path: docs/reference/supporting_tools/docs-ng/reference/testing.md +title: "Documentation Aggregation Testing Guide" +description: "Test suite for documentation - unit tests, integration tests, and testing best practices" --- -# docs-ng Testing Guide +# Documentation Aggregation Testing Guide -Test suite documentation for the docs-ng aggregation system. +Test suite documentation for the documentation aggregation system. > **Source Repository:** [gardenlinux/docs-ng](https://github.com/gardenlinux/docs-ng) > **Source File:** [tests/README.md](https://github.com/gardenlinux/docs-ng/blob/main/tests/README.md) @@ -227,6 +224,8 @@ Integration tests may fail if: ## See Also -- [Technical Reference](/reference/supporting_tools/docs-ng/reference/technical) — Source code documentation -- [Configuration Reference](/reference/supporting_tools/docs-ng/reference/configuration) — Configuration options -- [Architecture Explanation](/reference/supporting_tools/docs-ng/explanation/architecture) — System design +- [Getting Started Tutorial](../../tutorials/documentation/index.md) — Step-by-step guide to contributing documentation +- [Adding Repositories](../../how-to/documentation/adding-repos.md) — How to add new repositories to the aggregation +- [Technical Reference](../../reference/documentation/technical.md) — Source code and API documentation +- [Configuration Reference](../../reference/documentation/configuration.md) — Complete configuration options +- [Architecture Explanation](../../explanation/documentation/aggregation-architecture.md) — Deep dive into how the documentation aggregation system works diff --git a/docs/reference/supporting_tools/docs-ng/overview/index.md b/docs/reference/supporting_tools/docs-ng/overview/index.md deleted file mode 100644 index 1748327..0000000 --- a/docs/reference/supporting_tools/docs-ng/overview/index.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: "docs-ng Documentation Hub" -description: "Documentation aggregation system for Garden Linux - combines docs from multiple repositories into a unified VitePress site" -github_org: gardenlinux -github_repo: docs-ng -github_source_path: docs/reference/supporting_tools/docs-ng/overview/index.md ---- - -# docs-ng: Garden Linux Documentation Hub - -Build unified documentation from multiple Garden Linux repositories. - -> **Source Repository:** [gardenlinux/docs-ng](https://github.com/gardenlinux/docs-ng) - -## Overview - -docs-ng is the documentation aggregation system that powers the unified Garden Linux documentation site. It aggregates content from multiple source repositories (gardenlinux, builder, python-gardenlinux-lib) into a cohesive VitePress site. - -### Key Features - -- **Targeted Documentation**: Files with `github_target_path` frontmatter are automatically placed into the correct Diataxis categories -- **Project Mirroring**: Complete repository documentation mirrored under `docs/projects//` -- **Commit Locking**: Reproducible builds with locked commit hashes -- **Media Handling**: Automatic discovery and copying of media directories -- **Link Rewriting**: Automatic link transformation for cross-repository references - -### Documentation Paths - -The system supports two complementary documentation paths: - -1. **Targeted Documentation** — Files with `github_target_path` frontmatter → `docs/tutorials/`, `docs/how-to/`, etc. -2. **Project Mirror** — All repo docs mirrored under `docs/projects//` - -## Quick Start - -```bash -# Aggregate documentation from repos -make aggregate - -# Run development server -make dev - -# Build production site -make build -``` - -## Architecture Overview - -``` -Source Repos → Fetch (git/local) → Transform → docs/ → VitePress -``` - -The aggregation pipeline consists of four main stages: - -1. **Fetch** — `src/aggregation/fetcher.py` pulls docs via git sparse checkout or local copy -2. **Transform** — `src/aggregation/transformer.py` rewrites links, fixes frontmatter -3. **Structure** — `src/aggregation/structure.py` reorganizes directories and copies media -4. **Output** — VitePress builds the site - -## Project Structure - -``` -docs-ng/ -├── repos-config.json # Repository configuration -├── repos-config.local.json # Local development config -├── src/ # Source code -│ ├── aggregate.py # CLI entry point -│ └── aggregation/ # Core package -├── tests/ # Test suite -└── docs/ # Generated documentation - ├── projects/ # Mirrored repository docs - ├── tutorials/ # Aggregated tutorials - ├── how-to/ # Aggregated guides - ├── explanation/ # Aggregated explanations - └── reference/ # Aggregated reference docs -``` - -## Further Reading - -- [Getting Started Tutorial](/reference/supporting_tools/docs-ng/tutorials/getting_started) — Step-by-step guide to using docs-ng -- [Adding Repositories](/reference/supporting_tools/docs-ng/how-to/adding-repos) — How to add new repositories to the aggregation -- [Technical Reference](/reference/supporting_tools/docs-ng/reference/technical) — Source code and API documentation -- [Configuration Reference](/reference/supporting_tools/docs-ng/reference/configuration) — Complete configuration options -- [Architecture Explanation](/reference/supporting_tools/docs-ng/explanation/architecture) — Deep dive into how docs-ng works - -## Contributing - -See the [docs-ng repository](https://github.com/gardenlinux/docs-ng) for contribution guidelines. diff --git a/docs/reference/supporting_tools/docs-ng/tutorials/getting_started.md b/docs/reference/supporting_tools/docs-ng/tutorials/getting_started.md deleted file mode 100644 index 6f79f4e..0000000 --- a/docs/reference/supporting_tools/docs-ng/tutorials/getting_started.md +++ /dev/null @@ -1,152 +0,0 @@ ---- -title: "Getting Started with docs-ng" -description: "Step-by-step tutorial for setting up and using the docs-ng documentation aggregation system" -github_org: gardenlinux -github_repo: docs-ng -github_source_path: docs/reference/supporting_tools/docs-ng/tutorials/getting_started.md ---- - -# Getting Started with docs-ng - -This tutorial will walk you through setting up and using docs-ng to aggregate documentation from multiple repositories. - -> **Source Repository:** [gardenlinux/docs-ng](https://github.com/gardenlinux/docs-ng) - -## Prerequisites - -- Python 3.x -- pnpm (for VitePress) -- Git - -## Step 1: Clone the Repository - -```bash -git clone https://github.com/gardenlinux/docs-ng.git -cd docs-ng -``` - -## Step 2: Install Dependencies - -```bash -pnpm install -``` - -This installs VitePress and other Node.js dependencies needed to build the documentation site. - -## Step 3: Aggregate Documentation - -### From Remote Repositories (Production) - -Aggregate from locked commits in `repos-config.json`: - -```bash -make aggregate -``` - -This fetches documentation from the configured repositories at their locked commit hashes. - -### From Local Repositories (Development) - -For local development, use `repos-config.local.json` with `file://` URLs: - -```bash -make aggregate-local -``` - -This copies documentation from local repositories without using git. - -## Step 4: Start the Development Server - -```bash -make dev -``` - -The documentation site will be available at `http://localhost:5173`. - -## Step 5: Make Changes - -As you work on documentation in source repositories: - -1. Make changes to markdown files in source repos -2. Run `make aggregate-local` to update the aggregated docs -3. The dev server will hot-reload automatically - -## Step 6: Build for Production - -When ready to deploy: - -```bash -make build -``` - -This creates a production build in `docs/.vitepress/dist/`. - -## Common Workflows - -### Updating a Single Repository - -```bash -make aggregate-repo REPO=gardenlinux -``` - -### Updating Lock Files - -To fetch the latest commits and update `repos-config.json`: - -```bash -make aggregate-update -``` - -### Running Tests - -```bash -make test -``` - -## Project Structure - -After aggregation, your docs directory will look like: - -``` -docs/ -├── projects/ # Mirrored repository docs -│ ├── gardenlinux/ -│ ├── builder/ -│ └── python-gardenlinux-lib/ -├── tutorials/ # Aggregated tutorials -├── how-to/ # Aggregated guides -├── explanation/ # Aggregated explanations -├── reference/ # Aggregated reference -└── contributing/ # Aggregated contributing docs -``` - -## Next Steps - -- Learn how to [add new repositories](/reference/supporting_tools/docs-ng/how-to/adding-repos) -- Understand the [architecture](/reference/supporting_tools/docs-ng/explanation/architecture) -- Review the [configuration reference](/reference/supporting_tools/docs-ng/reference/configuration) - -## Troubleshooting - -### Clean Build - -If you encounter issues, try a clean build: - -```bash -make clean -make aggregate -make dev -``` - -### Check Dependencies - -Ensure all dependencies are installed: - -```bash -pnpm install -python3 --version # Should be 3.x -``` - -### Verify Configuration - -Check that `repos-config.json` or `repos-config.local.json` is properly configured. See the [configuration reference](/reference/supporting_tools/docs-ng/reference/configuration) for details. diff --git a/docs/tutorials/documentation/index.md b/docs/tutorials/documentation/index.md new file mode 100644 index 0000000..41e064a --- /dev/null +++ b/docs/tutorials/documentation/index.md @@ -0,0 +1,236 @@ +--- +title: "Contributing to the Garden Linux Documentation" +description: "Learn how to contribute to Garden Linux documentation — from quick edits to working with the aggregation system locally" +--- + +# Contributing to the Garden Linux Documentation + +Garden Linux documentation is published at **https://gardenlinux-docs.netlify.app/** and combines content from multiple repositories into a unified documentation site. + +> **Source Repository:** [gardenlinux/docs-ng](https://github.com/gardenlinux/docs-ng) + +## Quick Edits — The Easy Way + +The easiest way to improve the documentation is directly from the published site: + +1. **Navigate to any page** on https://gardenlinux-docs.netlify.app/ +2. **Scroll to the bottom** of the page +3. **Click "Edit this page on GitHub"** — this opens the source file in the correct repository +4. **Make your edits** using GitHub's web editor +5. **Submit a pull request** — the changes will be automatically aggregated into the documentation site + +### Why This Works + +The "Edit this page on GitHub" button is intelligent and takes you to the correct source location: + +- For content from the **main gardenlinux repository**, it links to `gardenlinux/gardenlinux/docs/...` +- For content from the **builder repository**, it links to `gardenlinux/builder/docs/...` +- For content from the **python-gardenlinux-lib repository**, it links to `gardenlinux/python-gardenlinux-lib/docs/...` +- For documentation-specific pages, it links to `gardenlinux/docs-ng/docs/...` + +**You don't need to understand the aggregation system to contribute!** The system automatically detects changes in source repositories and rebuilds the unified documentation site. + +This works because the VitePress configuration uses frontmatter metadata (`github_org`, `github_repo`, `github_source_path`, `github_branch`) embedded in each page to resolve the correct source location. + +This approach is perfect for: + +- Fixing typos +- Clarifying explanations +- Adding missing information +- Updating outdated content + +## Documentation Aggregation System + +The documentation aggregation system powers the unified Garden Linux documentation site. It aggregates content from multiple source repositories (gardenlinux, builder, python-gardenlinux-lib) into a cohesive VitePress site. + +### Key Features + +- **Targeted Documentation**: Files with `github_target_path` frontmatter are automatically placed into the correct Diataxis categories +- **Project Mirroring**: Complete repository documentation mirrored under `docs/projects//` +- **Commit Locking**: Reproducible builds with locked commit hashes +- **Media Handling**: Automatic discovery and copying of media directories +- **Link Rewriting**: Automatic link transformation for cross-repository references + +### Documentation Paths + +The system supports two complementary documentation paths: + +1. **Targeted Documentation** — Files with `github_target_path` frontmatter → `docs/tutorials/`, `docs/how-to/`, etc. +2. **Project Mirror** — All repo docs mirrored under `docs/projects//` + +### Architecture Overview + +``` +Source Repos → Fetch (git/local) → Transform → docs/ → VitePress +``` + +The aggregation pipeline consists of four main stages: + +1. **Fetch** — `src/aggregation/fetcher.py` pulls docs via git sparse checkout or local copy +2. **Transform** — `src/aggregation/transformer.py` rewrites links, fixes frontmatter +3. **Structure** — `src/aggregation/structure.py` reorganizes directories and copies media +4. **Output** — VitePress builds the 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 documentation system locally. + +#### Prerequisites + +- Python 3.x +- pnpm (for VitePress) +- Git + +#### Step 1: Clone the Repository + +```bash +git clone https://github.com/gardenlinux/docs-ng.git +cd docs-ng +``` + +#### Step 2: Install Dependencies + +```bash +pnpm install +``` + +This installs VitePress and other Node.js dependencies needed to build the documentation site. + +#### Step 3: Aggregate Documentation + +##### From Remote Repositories (Production) + +Aggregate from locked commits in `repos-config.json`: + +```bash +make aggregate +``` + +This fetches documentation from the configured repositories at their locked commit hashes. + +##### From Local Repositories (Development) + +For local development, use `repos-config.local.json` with `file://` URLs: + +```bash +make aggregate-local +``` + +This copies documentation from local repositories without using git. + +#### Step 4: Start the Development Server + +```bash +make dev +``` + +The documentation site will be available at `http://localhost:5173`. + +#### Step 5: Make Changes + +As you work on documentation in source repositories: + +1. Make changes to markdown files in source repos +2. Run `make aggregate-local` to update the aggregated docs +3. The dev server will hot-reload automatically + +#### Step 6: Build for Production + +When ready to deploy: + +```bash +make build +``` + +This creates a production build in `docs/.vitepress/dist/`. + +### Common Workflows + +#### Updating a Single Repository + +```bash +make aggregate-repo REPO=gardenlinux +``` + +#### Updating Lock Files + +To fetch the latest commits and update `repos-config.json`: + +```bash +make aggregate-update +``` + +#### Running Tests + +```bash +make test +``` + +### Project Structure + +#### Repository Structure (docs-ng) + +``` +docs-ng/ +├── repos-config.json # Repository configuration +├── repos-config.local.json # Local development config +├── src/ # Source code +│ ├── aggregate.py # CLI entry point +│ └── aggregation/ # Core package +├── tests/ # Test suite +└── docs/ # Generated documentation + ├── projects/ # Mirrored repository docs + ├── tutorials/ # Aggregated tutorials + ├── how-to/ # Aggregated guides + ├── explanation/ # Aggregated explanations + └── reference/ # Aggregated reference docs +``` + +#### After Aggregation + +After running the aggregation, your docs directory will look like: + +``` +docs/ +├── projects/ # Mirrored repository docs +│ ├── gardenlinux/ +│ ├── builder/ +│ └── python-gardenlinux-lib/ +├── tutorials/ # Aggregated tutorials +├── how-to/ # Aggregated guides +├── explanation/ # Aggregated explanations +├── reference/ # Aggregated reference +└── contributing/ # Aggregated contributing docs +``` + +### Troubleshooting + +#### Clean Build + +If you encounter issues, try a clean build: + +```bash +make clean +make aggregate +make dev +``` + +#### Check Dependencies + +Ensure all dependencies are installed: + +```bash +pnpm install +python3 --version # Should be 3.x +``` + +#### Verify Configuration + +Check that `repos-config.json` or `repos-config.local.json` is properly configured. See the [configuration reference](../../reference/documentation/configuration.md) for details. + +## Next Steps + +- [Adding Repositories](../../how-to/documentation/adding-repos.md) — How to add new repositories to the aggregation +- [Technical Reference](../../reference/documentation/technical.md) — Source code and API documentation +- [Configuration Reference](../../reference/documentation/configuration.md) — Complete configuration options +- [Architecture Explanation](../../explanation/documentation/aggregation-architecture.md) — Deep dive into how the documentation aggregation system works diff --git a/src/README.md b/src/README.md index 9841fb0..b123c7f 120000 --- a/src/README.md +++ b/src/README.md @@ -1 +1 @@ -../docs/reference/supporting_tools/docs-ng/reference/technical.md \ No newline at end of file +../docs/reference/documentation/technical.md \ No newline at end of file diff --git a/tests/README.md b/tests/README.md index ece7573..88c3f36 120000 --- a/tests/README.md +++ b/tests/README.md @@ -1 +1 @@ -../docs/reference/supporting_tools/docs-ng/reference/testing.md \ No newline at end of file +../docs/reference/documentation/testing.md \ No newline at end of file