From 949c86eed0165d3b15c00142f6124dacf8f21587 Mon Sep 17 00:00:00 2001 From: Danijel Simeunovic Date: Sat, 18 Apr 2026 20:29:43 +0200 Subject: [PATCH] docs --- .../docs.yml => .gitea/workflows/docs.yaml | 5 ++- .project-standards.yaml | 10 ++--- README.md | 10 ++++- docs/DEVELOPER-GUIDE.md | 42 +++++++++++++++++++ docs/REFERENCE.md | 23 ++++++++++ 5 files changed, 82 insertions(+), 8 deletions(-) rename .github/workflows/docs.yml => .gitea/workflows/docs.yaml (80%) diff --git a/.github/workflows/docs.yml b/.gitea/workflows/docs.yaml similarity index 80% rename from .github/workflows/docs.yml rename to .gitea/workflows/docs.yaml index 4d9dbf1..5717953 100644 --- a/.github/workflows/docs.yml +++ b/.gitea/workflows/docs.yaml @@ -6,9 +6,10 @@ on: paths: - 'docs/**' - 'mkdocs.yml' + - 'Dockerfile.docs' + - 'nginx.conf' workflow_dispatch: - jobs: build-and-deploy: runs-on: ubuntu-latest @@ -31,4 +32,4 @@ jobs: git config user.email "actions@forteapps.net" git add . git commit -m "Deploy docs" - git push --force "https://x-token:${{ secrets.GITEA_TOKEN }}@git.forteapps.net/Forte/launchpad.git" HEAD:gitea-pages + git push --force "https://x-token:${{ gitea.token }}@git.forteapps.net/Forte/launchpad.git" HEAD:gitea-pages diff --git a/.project-standards.yaml b/.project-standards.yaml index d7c9612..9fa8127 100644 --- a/.project-standards.yaml +++ b/.project-standards.yaml @@ -1,7 +1,7 @@ standards_version: "2025.1" -last_configured: "2026-04-04" +last_configured: "2026-04-18" components: - github-pages: "2025.1" - github-pages-generator: "mkdocs" - github-pages-source: "docs/" - github-pages-theme: "material" + gitea-pages: "2025.1" + gitea-pages-generator: "mkdocs" + gitea-pages-source: "docs/" + gitea-pages-theme: "material" diff --git a/README.md b/README.md index 9095ee0..b44e981 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,7 @@ [![GitOps](https://img.shields.io/badge/GitOps-ArgoCD-blue)](https://argoproj.github.io/cd/) [![Kubernetes](https://img.shields.io/badge/Kubernetes-UpCloud-orange)](https://upcloud.com/) +[![Docs](https://img.shields.io/badge/Docs-Gitea%20Pages-green)](https://git.forteapps.net/Forte/launchpad/pages/) --- @@ -11,6 +12,8 @@ **New developers and operators**: Please refer to our comprehensive documentation for detailed guides and references: +### 🌐 [**Live Documentation Site**](https://git.forteapps.net/Forte/launchpad/pages/) (Gitea Pages) + ### 🎯 [**START HERE: Documentation Index**](docs/README.md) | Document | Description | Audience | @@ -82,6 +85,10 @@ This repository contains the complete GitOps configuration for our Kubernetes cl . ├── bootstrap.sh # Cluster initialization script ├── _app-of-apps.yaml # Root ArgoCD Application (App-of-Apps pattern) +├── mkdocs.yml # MkDocs configuration (Gitea Pages) +│ +├── .gitea/workflows/ # Gitea Actions CI workflows +│ └── docs.yaml # Build & deploy MkDocs to Gitea Pages │ ├── infra/ # Infrastructure ArgoCD Applications (Kustomize multi-cluster) │ ├── base/ # Base ArgoCD Application manifests (EU defaults) @@ -344,6 +351,7 @@ kubectl patch application myapp -n argocd \ | **OpenCost** | Cost monitoring | `monitoring` | 1 | | **Renovate** | Dependency updates | `renovate` | CronJob | | **Trivy** | Vulnerability scanning | `trivy-system` | 1 | +| **Gitea Pages** | Documentation hosting | N/A (Gitea built-in) | N/A | **Full specs**: [Technical Reference - Infrastructure Components](docs/REFERENCE.md#infrastructure-components) @@ -504,7 +512,7 @@ Internal use only. Not for public distribution. --- -**Last Updated**: 2026-03-16 +**Last Updated**: 2026-04-18 **Documentation Version**: 1.0.0 **🚀 Ready to get started? Check out the [Documentation Index](docs/README.md)!** diff --git a/docs/DEVELOPER-GUIDE.md b/docs/DEVELOPER-GUIDE.md index 9a2f127..1e0d373 100644 --- a/docs/DEVELOPER-GUIDE.md +++ b/docs/DEVELOPER-GUIDE.md @@ -11,6 +11,7 @@ - [Enabling Authentication for Applications](#enabling-authentication-for-applications) - [Adding a New Keycloak Client](#adding-a-new-keycloak-client) - [Troubleshooting](#troubleshooting) +- [Documentation](#documentation) - [Best Practices](#best-practices) --- @@ -1627,6 +1628,47 @@ If you're stuck: --- +## Documentation + +This repository's documentation is built with [MkDocs](https://www.mkdocs.org/) using the [Material](https://squidfund.github.io/mkdocs-material/) theme and published automatically to Gitea Pages. + +### Viewing the Docs + +The live documentation site is available at: + +**https://git.forteapps.net/Forte/launchpad/pages/** + +### Editing Documentation + +All documentation source files live in the `docs/` directory as Markdown. To make changes: + +1. Edit the relevant `.md` file in `docs/` +2. Commit and push to `main` +3. The Gitea Actions workflow automatically rebuilds and deploys the site + +### Local Preview + +To preview documentation changes locally before pushing: + +```bash +# Install dependencies (one-time) +pip install mkdocs mkdocs-material + +# Start the local dev server +mkdocs serve +``` + +Then open `http://127.0.0.1:8000` in your browser. The server live-reloads on file changes. + +### How It Works + +- **Workflow**: `.gitea/workflows/docs.yaml` triggers on pushes to `main` that change `docs/**`, `mkdocs.yml`, `Dockerfile.docs`, or `nginx.conf` +- **Build**: Installs MkDocs + Material theme, runs `mkdocs build` +- **Deploy**: Force-pushes the built `site/` directory to the `gitea-pages` branch +- **Serve**: Gitea Pages serves the static site from the `gitea-pages` branch + +--- + ## Best Practices ### Development Workflow diff --git a/docs/REFERENCE.md b/docs/REFERENCE.md index 4732b68..c0296a3 100644 --- a/docs/REFERENCE.md +++ b/docs/REFERENCE.md @@ -1038,6 +1038,29 @@ resources: - `kubectl create job --from=cronjob/renovate renovate-test -n renovate` — manual trigger - `kubectl logs -n renovate job/renovate-test` — check logs +### Gitea Pages + +**Purpose**: Hosts the MkDocs documentation site for this repository. + +**How It Works**: +- A Gitea Actions workflow (`.gitea/workflows/docs.yaml`) builds MkDocs on push to `main` +- The built site is force-pushed to the `gitea-pages` branch +- Gitea serves the static site from that branch + +**URL**: `https://git.forteapps.net/Forte/launchpad/pages/` + +**Configuration**: +- Gitea server config: `ENABLE_GITEA_PAGES: true` (in gitea-values.yaml) +- MkDocs config: `mkdocs.yml` (repo root) +- Source files: `docs/` directory +- Theme: Material for MkDocs + +**Trigger Paths**: +- `docs/**` +- `mkdocs.yml` +- `Dockerfile.docs` +- `nginx.conf` + --- ## Kyverno Policies