diff --git a/docs/contributor-setup.md b/docs/contributor-setup.md new file mode 100644 index 00000000..6ef703c6 --- /dev/null +++ b/docs/contributor-setup.md @@ -0,0 +1,136 @@ +## Setting Up docforge Locally for Contributing + +### Prerequisites + +Before you begin, ensure you have the following installed on your system: + +- [Go](https://go.dev/dl/) +- [Git](https://git-scm.com/downloads) +- Make + - **Windows**: See [Windows Setup Options](#windows-setup-options) below + - **Mac**: Run `xcode-select --install` + - **Linux**: Usually pre-installed + +Verify the installation: + +```sh +go version +git --version +make --version +``` + +#### Windows Setup Options + +If you are on a Windows system, then you have several options for running docforge: + +**Option 1: WSL (Windows Subsystem for Linux)** + +WSL provides a native Linux environment on Windows, making it the easiest way to use docforge with full compatibility. + +1. Install WSL: + + ```powershell + # Run in PowerShell as Administrator + wsl --install + ``` + + This command will install WSL with Ubuntu by default. Restart your computer when prompted. + +1. Open WSL by searching for and launching "Ubuntu" in the Windows Start menu. + +1. Install prerequisites in WSL: + + ```bash + # Update package manager + sudo apt update + + # Install Go + wget https://go.dev/dl/go1.21.0.linux-amd64.tar.gz + sudo tar -C /usr/local -xzf go1.21.0.linux-amd64.tar.gz + echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc + source ~/.bashrc + + # Install Git and Make (usually pre-installed) + sudo apt install git make + ``` + +1. Continue with the [installation steps](#installation) below using the WSL terminal + +**Option 2: Git Bash** + +1. Install [Git for Windows](https://git-scm.com/downloads) which includes Git Bash: +1. Continue with the [installation steps](#installation) below using the GitBash terminal + +> [!NOTE] +> If you are working on Windows, it is advisable to run all commands on Git, as the Makefile uses Unix-style bash scripts which may not work directly on Windows PowerShell or CMD. + +### Installation + +1. Clone the docforge repository locally via Git: + + ```bash + git clone https://github.com/gardener/docforge.git + cd docforge + ``` + +1. Build Docforge (with Make): + + ```bash + make build-local + ``` + +1. Verify the installation: + + ```bash + ./bin/docforge --help + ``` + +### Configuration + +1. Create a GitHub Token: + 1. Navigate to `GitHub Settings > Developer Settings > Personal Access Tokens` + 2. Generate a new token with a `repo` scope + 3. Save the token securely + +1. Set the token as an environment variable: + + ```sh + export GITHUB_TOKEN="your_token_here" + ``` + +1. Create a configuration file (e.g., `docforge-config.yaml`) with the following content: + + ```yaml + manifest: path/to/your/manifest.yaml + destination: ./output + hugo: true + content-files-formats: + - ".md" + - ".html" + - ".png" + - ".jpg" + - ".svg" + markdown-enabled: true + skip-link-validation: true + ``` + +1. Run docforge: + + ```sh + export DOCFORGE_CONFIG="docforge-config.yaml" + ./bin/docforge --github-oauth-env-map "github.com=GITHUB_TOKEN" + ``` + +## Testing Your Setup + +1. Check the docforge version: + + ```bash + ./bin/docforge version + ``` + +1. Perform a dry run (tests without creating any files): + + ```sh + ./bin/docforge -f manifest.yaml -d output --dry-run + ``` diff --git a/docs/issues.md b/docs/issues.md new file mode 100644 index 00000000..317ea636 --- /dev/null +++ b/docs/issues.md @@ -0,0 +1,28 @@ +## Troubleshooting + +### Issue: "no resource handlers were loaded" + +**Cause**: Missing GitHub OAuth token configuration + +**Solution**: Ensure you have: + +1. Created a GitHub personal access token +1. Set it as an environment variable +1. Referenced it in the `--github-oauth-env-map` flag + +### Issue: Build fails on Windows with Makefile + +**Cause**: Makefile uses Unix-style bash commands + +**Solution**: Use the direct `go build` command instead of `make` + +- Command: `go build -v -o bin/docforge.exe -ldflags "-w -X github.com/gardener/docforge/cmd/version.Version=v0.57.0-dev" ./cmd` + +### Issue: Command not found (Windows) + +**Cause**: Trying to run bash scripts on Windows + +**Solution**: Either: + +- Install Git Bash or WSL +- Use direct Go commands diff --git a/tasks/images/evil-lord.png b/tasks/images/evil-lord.png new file mode 100644 index 00000000..54d1be4c Binary files /dev/null and b/tasks/images/evil-lord.png differ diff --git a/tasks/images/scholar.png b/tasks/images/scholar.png new file mode 100644 index 00000000..c85a599f Binary files /dev/null and b/tasks/images/scholar.png differ diff --git a/tasks/images/times-before.png b/tasks/images/times-before.png new file mode 100644 index 00000000..9172d5ab Binary files /dev/null and b/tasks/images/times-before.png differ diff --git a/tasks/pieces/part-1.md b/tasks/pieces/part-1.md new file mode 100644 index 00000000..32fab672 --- /dev/null +++ b/tasks/pieces/part-1.md @@ -0,0 +1,63 @@ +--- +title: Podrick and the Infinite Garden +weight: 0 +--- + +# Podrick and the Infinite Garden + +![cover picture of podrick and the infinite garden](./images/podrick/scene-0.png) + +* **Written by:** _The Gardener authors_ +* **Inspiration:** [_The Illustrated Children's Guide to Kubernetes_](https://www.cncf.io/phippy/the-childrens-illustrated-guide-to-kubernetes/) +* **Illustrations:** _generated with [Gemini Nano Banana Pro](https://gemini.google/overview/image-generation/)_ + +## Meet Podrick + +Podrick was a simple earthworm with a complex dream. +While most worms were content tunneling through a single patch of dirt, Podrick had ambition. +He had collected thousands of rare and delicate plants. +Among them were orchids that needed humidity, cacti that craved dry heat, and ferns that demanded shade. + +To keep them alive, he needed plots (_Kubernetes clusters_). +Many plots in different environments but all with a similar set of features to ease maintenance efforts. + +![podrick is an earthworm and main protagonist of the story](./images/podrick/podrick_no_logo.png) + +## _Explanation: Kubernetes Clusters_ + +* Host containerized workloads. +* Can be configured in many ways. +* Need to be scaled, updated and maintained regularly. + +a farm plot growing different vegetables representing a kubernetes cluster + +--- + +At first, Podrick had asked his racoon friends for help. + +The raccoons were enthusiastic builders, but they were chaotic. +"Hey Podrick!" a raccoon shouted, straining to shove a green hose into a square pipe. +"I've built the perfect intake system!" +"That's great," Podrick sighed, "but how do I connect your intake system to the other plots?" + +He turned to the second raccoon, who was cluelessly trying to drill holes into a puddle of water. +"I have the most advanced tools," the raccoon insisted, "but for some reason, I don't seem to make any progress!" + +Meanwhile, the third raccoon ignored them both, meticulously sorting and stacking smooth pebbles. +It was a beautiful way of organizing, but it didn't help Podrick on the quest for the perfect plot. + +Each built their own way, using their own tools, speaking their own languages. +If a plot broke, Podrick had to find the builder and understand their logic. +Podrick was tired. + +![podrick meets three raccoons that represent providers of kubernetes distributions](./images/podrick/scene-1.png) + +## _Explanation: Providers_ + +* There are many ways to get and maintain a Kubernetes cluster. +* Different offerings provide different features and configuration options. +* Each provider has their own release/adoption cycle for new Kubernetes version and features. + +raccoon representing a kubernetes provider + +--- \ No newline at end of file diff --git a/tasks/podrick.yaml b/tasks/podrick.yaml new file mode 100644 index 00000000..68d45ea1 --- /dev/null +++ b/tasks/podrick.yaml @@ -0,0 +1,24 @@ +structure: + # Combined document from multiple sources + - file: combined-story.md + frontmatter: + title: "Podrick's Complete Story" + weight: 1 + multiSource: + # Part 1 - Local file + - /tasks/pieces/part-1.md + + # Parts 2-4 - You need to specify individual .md files from those directories + # Example (replace with actual filenames): + - https://github.com/n-boshnakov/old-ruins/blob/moment-of-rest/common-room/part-2.md + - https://github.com/n-boshnakov/old-ruins/blob/lost-moment/dining-room/part-3.md + - https://github.com/n-boshnakov/old-ruins/blob/moment-of-rest/common-room/part-4.md + - https://github.com/n-boshnakov/old-ruins/blob/lost-moment/dining-room/part-5.md + - https://github.com/n-boshnakov/old-ruins/blob/eventful-moment/ball-room/part-6.md + - https://github.com/n-boshnakov/old-ruins/blob/eventful-moment/ball-room/part-7.md + - https://github.com/n-boshnakov/marketplace/blob/main/unassuming-stall/other-wares/cookbook.md + + # Images directory - download separately + - dir: images + structure: + - fileTree: https://github.com/n-boshnakov/marketplace/tree/main/unassuming-stall/orb-of-sight \ No newline at end of file diff --git a/tasks/save_podrick.md b/tasks/save_podrick.md new file mode 100644 index 00000000..c41a7058 --- /dev/null +++ b/tasks/save_podrick.md @@ -0,0 +1,29 @@ +## Save Podrick's Story + +The [story of Podrick](https://gardener.cloud/docs/getting-started/podrick-and-the-infinite-garden/) has traveled to distant lands and inspired everyone to create their own little gardens. Beautiful flowers, delicious vegetables, and bushes full of berries have taken over spots that used to lay barren. No matter the climate, the needs of the crops or the layout of the plots, Podrick's exploits gave the people strength to overcome any obstacles. + +![what-was-before](./images/times-before.png) + +--- + +But beauty has a way of attracting the attention of envious eyes. The evil Lord [Placeholder] has ruled over the land for decades through fear and keeping the spirits of his subjects low. To him, optimism and effort are a threat, so he had all scrolls and books detailing Podrick's exploits gathered, torn to shreds and burned. With these teachings lost, now nary a trace remains of the beautiful gardens that were. + +![evil-lord](./images/evil-lord.png) + +--- + +Yet a faint hope remains still. Your teacher, the wise scholar doc. Forge, has come across a piece of the original story tucked away in a dusty old tome, seemingly untouched for years. It appears that someone, maybe a hesitant servant of Lord [Placeholder], maybe a kind soul revolting at the thought of destroying such knowledge, has preserved what little they could of the invaluable texts. + +![scholar](./images/scholar.png) + +On the back of that first piece of the scroll were marked two locations hidden from Lord [Placeholder]'s prying eyes - an [old, long forgotten ruin of the times long past](https://github.com/n-boshnakov/old-ruins), and [an unassuming market stall in the city's busiest market](https://github.com/n-boshnakov/marketplace). + +As doc. Forge is not as spry as he used to be, the task of going to these places and locating the missing pieces of the story falls on your shoulders. Armed with only your wits and a blank piece of the original Scroll of Desire gifted to you by your teacher, you set off on your journey. + +The magic of the scroll allows you to access the contents of any location by simply writing it down in the correct format. Use that to collect the missing pieces and help your mentor complete the original scroll! + +## Task + +Update the existing docforge manifest so that it collects all parts of the Podrick story from the [old-ruins](https://github.com/n-boshnakov/old-ruins) and [marketplace](https://github.com/n-boshnakov/marketplace) repositories. To make this task easier on doc. Forge, make sure that each part is named `part-` and placed in the [`pieces` folder](./pieces/), and that all images are placed in a separate folder. + +Use the provided [manifest reference documentation](./docs/manifests.md) for help when [updating the manifest](./tasks/podrick.yaml).