From ebbbd2f7c53cb4b43296e01f40f27e29cdce8e87 Mon Sep 17 00:00:00 2001 From: Eike Waldt Date: Tue, 7 Apr 2026 14:45:13 +0200 Subject: [PATCH] docs: add tutorial and howto for docs-ng Signed-off-by: Eike Waldt On-behalf-of: SAP --- .gitignore | 1 + docs/how-to/documentation/working-locally.md | 162 ++++++++++++++++++ docs/overview/index.md | 14 +- docs/reference/documentation/configuration.md | 2 + docs/reference/documentation/technical.md | 2 + docs/reference/documentation/testing.md | 1 + docs/tutorials/documentation.md | 28 +++ 7 files changed, 203 insertions(+), 7 deletions(-) create mode 100644 docs/how-to/documentation/working-locally.md create mode 100644 docs/tutorials/documentation.md diff --git a/.gitignore b/.gitignore index ab73b32..e1c6a07 100644 --- a/.gitignore +++ b/.gitignore @@ -36,4 +36,5 @@ docs/reference/supporting_tools/** docs/tutorials/** !docs/tutorials/documentation/ !docs/tutorials/documentation/** +!docs/tutorials/documentation.md !docs/tutorials/index.md diff --git a/docs/how-to/documentation/working-locally.md b/docs/how-to/documentation/working-locally.md new file mode 100644 index 0000000..26870e3 --- /dev/null +++ b/docs/how-to/documentation/working-locally.md @@ -0,0 +1,162 @@ +--- +title: "Contributing to the Garden Linux Documentation" +description: "Learn how to contribute to Garden Linux documentation — 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) + +## 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 + +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](../../how-to/documentation/adding-repos) +- Understand the [architecture](../../explanation/architecture) +- Review the [configuration reference](../../reference/documentation/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/documentation/configuration) for details. + +## See Also + +- [Quick Edits](../../tutorials/documentation.md) +- [Working with the Documentation System Locally](../../how-to/documentation/working-locally.md) +- [Testing Reference](../../reference/documentation/testing.md) — Test suite documentation +- [Adding Repositories](../../how-to/documentation/adding-repos.md) — How to add new repos +- [Technical Reference](../../reference/documentation/technical.md) — Source code documentation +- [Architecture](../../explanation/documentation/aggregation-architecture.md) — System design diff --git a/docs/overview/index.md b/docs/overview/index.md index 0bd1093..48356cf 100644 --- a/docs/overview/index.md +++ b/docs/overview/index.md @@ -10,14 +10,14 @@ Garden Linux documentation uses the [Diátaxis framework](https://diataxis.fr/) ## Where to Start -| Your Situation | Where to Go | -| --- | --- | -| New to Garden Linux | Start with [Tutorials](/tutorials/) | +| Your Situation | Where to Go | +| ----------------------------- | ------------------------------------------------------------ | +| New to Garden Linux | Start with [Tutorials](/tutorials/) | | Deploy on a specific platform | Go to [Platform-Specific Guides](/how-to/platform-specific/) | -| Customize Garden Linux | Check [Customization Guides](/how-to/customization/) | -| Understand concepts | Read [Explanation](/explanation/) | -| Look up specifications | Search [Reference](/reference/) | -| Contribute to the project | See [Contributing](/contributing/) | +| Customize Garden Linux | Check [Customization Guides](/how-to/customization/) | +| Understand concepts | Read [Explanation](/explanation/) | +| Look up specifications | Search [Reference](/reference/) | +| Contribute to the project | See [Contributing](/contributing/) | ## Tutorials diff --git a/docs/reference/documentation/configuration.md b/docs/reference/documentation/configuration.md index eef5d4d..6d205bd 100644 --- a/docs/reference/documentation/configuration.md +++ b/docs/reference/documentation/configuration.md @@ -299,6 +299,8 @@ These help create source links in the documentation. ## See Also +- [Working with the Documentation System Locally](../../how-to/documentation/working-locally.md) +- [Testing Reference](./testing.md) — Test suite documentation - [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/documentation/technical.md b/docs/reference/documentation/technical.md index e930641..b4c78e1 100644 --- a/docs/reference/documentation/technical.md +++ b/docs/reference/documentation/technical.md @@ -173,6 +173,8 @@ Key architectural decisions are documented in the source repository: ## See Also +- [Working with the Documentation System Locally](../../how-to/documentation/working-locally.md) - [Testing Reference](./testing.md) — Test suite documentation +- [Adding Repositories](../../how-to/documentation/adding-repos.md) — How to add new repos - [Configuration Reference](./configuration.md) — Complete configuration field reference - [Architecture Explanation](../../explanation/documentation/aggregation-architecture.md) — How the system works diff --git a/docs/reference/documentation/testing.md b/docs/reference/documentation/testing.md index b05c0e2..8253d16 100644 --- a/docs/reference/documentation/testing.md +++ b/docs/reference/documentation/testing.md @@ -224,6 +224,7 @@ Integration tests may fail if: ## See Also +- [Working with the Documentation System Locally](../../how-to/documentation/working-locally.md) - [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 diff --git a/docs/tutorials/documentation.md b/docs/tutorials/documentation.md new file mode 100644 index 0000000..e61021e --- /dev/null +++ b/docs/tutorials/documentation.md @@ -0,0 +1,28 @@ +--- +title: "Contributing to the Garden Linux Documentation" +description: "Learn how to contribute to Garden Linux documentation — quick edits" +--- + +# 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 + +## See Also + +- [Working with the Documentation System Locally](../how-to/documentation/working-locally.md) +- [Testing Reference](../reference/documentation/testing.md) — Test suite documentation +- [Adding Repositories](../how-to/documentation/adding-repos.md) — How to add new repos +- [Technical Reference](../reference/documentation/technical.md) — Source code documentation +- [Architecture](../explanation/documentation/aggregation-architecture.md) — System design