From 990d706846e1719af669a7712f5147f69605c5d9 Mon Sep 17 00:00:00 2001 From: Felix Delattre Date: Fri, 24 Oct 2025 16:34:17 +0200 Subject: [PATCH 1/2] refactor: documentation structure. --- .github/workflows/validate-docs-links.yml | 162 +++++++++++++++++++ CHANGELOG.md | 2 + Makefile | 7 +- README.md | 2 +- charts/eoapi/README.md | 6 +- docs/_includes/repository-links.md | 8 + docs/{operations => }/autoscaling.md | 30 +++- docs/{installation/providers => }/aws-eks.md | 14 ++ docs/{installation/providers => }/azure.md | 14 ++ docs/{installation => }/configuration.md | 14 +- docs/docs-config.json | 54 +++++++ docs/{installation/providers => }/gcp-gke.md | 18 ++- docs/{installation => }/helm-install.md | 12 ++ docs/index.md | 38 +++-- docs/{operations => }/manage-data.md | 12 ++ docs/{installation => }/quick-start.md | 10 ++ docs/{advanced => }/release.md | 12 ++ docs/{advanced => }/stac-auth-proxy.md | 10 ++ docs/{installation => }/unified-ingress.md | 14 ++ scripts/generate-portable-docs.sh | 103 ++++++++++++ 20 files changed, 511 insertions(+), 31 deletions(-) create mode 100644 .github/workflows/validate-docs-links.yml create mode 100644 docs/_includes/repository-links.md rename docs/{operations => }/autoscaling.md (93%) rename docs/{installation/providers => }/aws-eks.md (95%) rename docs/{installation/providers => }/azure.md (94%) rename docs/{installation => }/configuration.md (91%) create mode 100644 docs/docs-config.json rename docs/{installation/providers => }/gcp-gke.md (86%) rename docs/{installation => }/helm-install.md (81%) rename docs/{operations => }/manage-data.md (81%) rename docs/{installation => }/quick-start.md (88%) rename docs/{advanced => }/release.md (78%) rename docs/{advanced => }/stac-auth-proxy.md (94%) rename docs/{installation => }/unified-ingress.md (90%) create mode 100755 scripts/generate-portable-docs.sh diff --git a/.github/workflows/validate-docs-links.yml b/.github/workflows/validate-docs-links.yml new file mode 100644 index 00000000..9c17e2c7 --- /dev/null +++ b/.github/workflows/validate-docs-links.yml @@ -0,0 +1,162 @@ +name: Validate Documentation Links + +on: + push: + branches: [ main, master ] + paths: [ 'docs/**/*.md' ] + pull_request: + branches: [ main, master ] + paths: [ 'docs/**/*.md' ] + +jobs: + validate-links: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '18' + + - name: Install markdown-link-check + run: npm install -g markdown-link-check + + - name: Create markdown-link-check config + run: | + cat > .markdown-link-check.json << 'EOF' + { + "ignorePatterns": [ + { + "pattern": "^https://github.com/developmentseed/eoapi-k8s" + }, + { + "pattern": "localhost" + }, + { + "pattern": "127.0.0.1" + } + ], + "replacementPatterns": [ + { + "pattern": "^./", + "replacement": "{{BASEURL}}/" + } + ], + "httpHeaders": [ + { + "urls": ["https://github.com"], + "headers": { + "Accept": "text/html" + } + } + ], + "timeout": "20s", + "retryOn429": true, + "retryCount": 3, + "fallbackRetryDelay": "30s", + "aliveStatusCodes": [200, 206, 301, 302, 403, 999] + } + EOF + + - name: Validate internal links + run: | + echo "Checking internal link patterns..." + broken_links_found=0 + + while IFS= read -r -d '' file; do + echo "Checking internal links in: $file" + + # Check for broken relative links + while IFS=: read -r line_num link; do + # Extract the link path + link_path=$(echo "$link" | sed -n 's/.*](\.\///; s/).*//p') + + # Check if it's an image link + if [[ "$link_path" == images/* ]]; then + full_path="docs/$link_path" + else + full_path="docs/$link_path" + fi + + if [[ ! -e "$full_path" ]]; then + echo "❌ Broken internal link in $file:$line_num -> $link_path (resolved to: $full_path)" + broken_links_found=1 + else + echo "✅ Valid internal link: $link_path" + fi + done < <(grep -n "](\./" "$file" || true) + done < <(find docs -name "*.md" -type f -print0) + + if [[ $broken_links_found -eq 1 ]]; then + echo "❌ Found broken internal links!" + exit 1 + else + echo "✅ All internal links are valid!" + fi + + - name: Validate external links + run: | + echo "Validating external links..." + find docs -name "*.md" -type f | while read -r file; do + echo "Checking external links in: $file" + markdown-link-check "$file" --config .markdown-link-check.json || echo "Some external links failed in $file" + done + + - name: Check for consistent link patterns + run: | + echo "Checking for inconsistent link patterns..." + inconsistent_found=false + + # Check for bad patterns + if find docs -name "*.md" -exec grep -l "](docs/" {} \;; then + echo "❌ Found links using 'docs/' prefix - use relative paths instead" + find docs -name "*.md" -exec grep -Hn "](docs/" {} \; + inconsistent_found=true + fi + + if find docs -name "*.md" -exec grep -l "](\.\./" {} \;; then + echo "❌ Found links using '../' - use relative paths from docs root instead" + find docs -name "*.md" -exec grep -Hn "](\.\./" {} \; + inconsistent_found=true + fi + + if [[ "$inconsistent_found" == "true" ]]; then + echo "❌ Found inconsistent link patterns!" + echo "Use these patterns instead:" + echo " - [Installation Guide](./installation.md)" + echo " - [AWS Setup](./aws-eks.md)" + echo " - [Images](./images/diagram.png)" + exit 1 + else + echo "✅ All link patterns are consistent!" + fi + + - name: Validate frontmatter + run: | + echo "Checking that all markdown files have frontmatter..." + missing_frontmatter_found=0 + + while IFS= read -r -d '' file; do + if ! head -1 "$file" | grep -q "^---$"; then + echo "❌ Missing frontmatter in: $file" + missing_frontmatter_found=1 + fi + done < <(find docs -name "*.md" -not -path "docs/_includes/*" -type f -print0) + + if [[ $missing_frontmatter_found -eq 1 ]]; then + echo "❌ Some files are missing frontmatter!" + echo "Add frontmatter like:" + echo "---" + echo "title: \"Page Title\"" + echo "description: \"Page description\"" + echo "external_links:" + echo " - name: \"Link Name\"" + echo " url: \"https://example.com\"" + echo "---" + exit 1 + else + echo "✅ All markdown files have frontmatter!" + fi diff --git a/CHANGELOG.md b/CHANGELOG.md index 6a09ab58..a6346748 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +- Restructured docs with flattened structure and added portable documentation generation + ## [0.7.12] - 2025-10-17 - Bumped eoapi-notifier dependency version to 0.0.7 diff --git a/Makefile b/Makefile index 5fae9ef2..28666927 100755 --- a/Makefile +++ b/Makefile @@ -5,7 +5,7 @@ HELM_REPO_URL=https://devseed.com/eoapi-k8s/ HELM_CHART_NAME=eoapi/eoapi PGO_CHART_VERSION=5.7.4 -.PHONY: all deploy minikube ingest tests integration lint validate-schema help +.PHONY: all deploy minikube ingest tests integration lint validate-schema docs help # Default target all: deploy @@ -25,6 +25,11 @@ minikube: @echo "eoAPI is now available at:" @minikube service ingress-nginx-controller -n ingress-nginx --url | head -n 1 +docs: + @echo "Generating portable documentation package." + @command -v bash >/dev/null 2>&1 || { echo "bash is required but not installed"; exit 1; } + @./scripts/generate-portable-docs.sh + ingest: @echo "Ingesting STAC collections and items into the database." @command -v bash >/dev/null 2>&1 || { echo "bash is required but not installed"; exit 1; } diff --git a/README.md b/README.md index 4969613d..56eec7ba 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ ### Get started -* [Quick start guide](./docs/installation/quick-start.md) +* [Quick start guide](./docs/quick-start.md) ### `eoAPI-k8s` documentation diff --git a/charts/eoapi/README.md b/charts/eoapi/README.md index a7a95cdf..48e21e88 100644 --- a/charts/eoapi/README.md +++ b/charts/eoapi/README.md @@ -114,9 +114,9 @@ postgresql: For detailed configuration and usage: -- [Configuration Guide](https://github.com/developmentseed/eoapi-k8s/blob/main/docs/installation/configuration.md) -- [Data Management](https://github.com/developmentseed/eoapi-k8s/blob/main/docs/operations/manage-data.md) -- [Autoscaling Guide](https://github.com/developmentseed/eoapi-k8s/blob/main/docs/operations/autoscaling.md) +- [Configuration Guide](https://github.com/developmentseed/eoapi-k8s/blob/main/docs/configuration.md) +- [Data Management](https://github.com/developmentseed/eoapi-k8s/blob/main/docs/manage-data.md) +- [Autoscaling Guide](https://github.com/developmentseed/eoapi-k8s/blob/main/docs/autoscaling.md) ## License diff --git a/docs/_includes/repository-links.md b/docs/_includes/repository-links.md new file mode 100644 index 00000000..34e32ae8 --- /dev/null +++ b/docs/_includes/repository-links.md @@ -0,0 +1,8 @@ + +[Main eoapi Repository]: https://github.com/developmentseed/eoapi +[eoapi-k8s Repository]: https://github.com/developmentseed/eoapi-k8s +[Report Issues]: https://github.com/developmentseed/eoapi-k8s/issues +[eoAPI Documentation]: https://eoapi.dev/ +[Helm Charts]: https://github.com/developmentseed/eoapi-k8s/tree/main/charts +[PostgreSQL Operator]: https://access.crunchydata.com/documentation/postgres-operator/ +[Kubernetes Documentation]: https://kubernetes.io/docs/ diff --git a/docs/operations/autoscaling.md b/docs/autoscaling.md similarity index 93% rename from docs/operations/autoscaling.md rename to docs/autoscaling.md index 2ad25aa2..f5f76d8a 100644 --- a/docs/operations/autoscaling.md +++ b/docs/autoscaling.md @@ -1,3 +1,17 @@ +--- +title: "Autoscaling & Monitoring" +description: "HPA setup with custom metrics, Grafana dashboards, Prometheus configuration, and load testing" +external_links: + - name: "eoapi-k8s Repository" + url: "https://github.com/developmentseed/eoapi-k8s" + - name: "Kubernetes HPA Documentation" + url: "https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/" + - name: "Prometheus Documentation" + url: "https://prometheus.io/docs/" + - name: "Grafana Documentation" + url: "https://grafana.com/docs/" +--- + # Autoscaling / Monitoring / Observability Autoscaling is both art and science. To test out your application's autoscaling requirements you often need to consider @@ -5,7 +19,7 @@ your data volume, data usage patterns, bottlenecks (such as the database) among metrics, monitoring and observability will help you explore what those needs are. -> ⓘ The `eoapi-support` chart in this repository (see `../charts/eoapi-support`) is required to be installed to +> ⓘ The `eoapi-support` chart in this repository is required to be installed to enable any of the eoAPI service autoscaling. It cannot be listed as a dependecy of `eoapi` chart b/c of the limitations in `prometheus-adapter` and `grafana` for constructing the Prometheus internal service domains dynamically. @@ -17,7 +31,7 @@ might want to read through the verbose walkthrough material below to familiarize ## Helm Install `eoapi-support` -The following instructions assume you've gone through the [AWS](../installation/providers/aws-eks.md) or [GCP](../installation/providers/gcp-gke.md) cluster set up +The following instructions assume you've gone through the [AWS](./aws-eks.md) or [GCP](./gcp-gke.md) cluster set up and installed the `eoapi` chart. @@ -99,9 +113,9 @@ manual step that cannot be automated --- -### Review [Default Configuration and Options](../installation/configuration.md) +### Review [Default Configuration and Options](./configuration.md) -[This document](../installation/configuration.md) will explain the differences in the `autoscaling` block for each service: +[This document](./configuration.md) will explain the differences in the `autoscaling` block for each service: ```yaml autoscaling: @@ -199,15 +213,15 @@ with the `release` name we installed the chart with below `-grafan 3. Login and you should be default be able to see the eoapi-k8s grafana dashboard. The Prometheus datasource will already be configured for you: - ![Grafana Datasource Configuration](../images/datasource.png) + ![Grafana Datasource Configuration](./images/datasource.png) You can then view the main eoAPI dashboard: - ![](../images/gfdashboard.png) + ![](./images/gfdashboard.png) To add additional custom dashboards, you can use the dashboard import functionality: - ![Adding Custom Grafana Dashboards](../images/add-grafana-dashboard.png) + ![Adding Custom Grafana Dashboards](./images/add-grafana-dashboard.png) ### Install or Upgrade Autoscaling Changes to `eoapi` Chart @@ -361,7 +375,7 @@ that you're deploying using `ingress.className: "nginx"`. 4. **Monitor autoscaling in Grafana** - Go back to your Grafana dashboard and watch your services autoscale for the endpoints you're hitting: - ![Grafana Autoscaling Dashboard](../images/grafanaautoscale.png) + ![Grafana Autoscaling Dashboard](./images/grafanaautoscale.png) ### Load Testing Best Practices diff --git a/docs/installation/providers/aws-eks.md b/docs/aws-eks.md similarity index 95% rename from docs/installation/providers/aws-eks.md rename to docs/aws-eks.md index f0fc9181..59376e97 100644 --- a/docs/installation/providers/aws-eks.md +++ b/docs/aws-eks.md @@ -1,3 +1,17 @@ +--- +title: "AWS EKS Setup" +description: "Complete EKS cluster setup with OIDC, node autoscaling, EBS CSI, and NGINX ingress" +external_links: + - name: "eoapi-k8s Repository" + url: "https://github.com/developmentseed/eoapi-k8s" + - name: "AWS EKS Documentation" + url: "https://docs.aws.amazon.com/eks/" + - name: "eksctl Documentation" + url: "https://eksctl.io/" + - name: "Terraform Alternative" + url: "https://github.com/developmentseed/eoapi-k8s-terraform" +--- + # AWS EKS Cluster Walkthrough This is a verbose walkthrough. It uses `eksctl` and assumes you already have an AWS account, have the [eksctl prerequisites installed](https://docs.aws.amazon.com/eks/latest/userguide/getting-started-eksctl.html) including `eksctl` and `helm`. diff --git a/docs/installation/providers/azure.md b/docs/azure.md similarity index 94% rename from docs/installation/providers/azure.md rename to docs/azure.md index 1c008907..1ae56b6f 100644 --- a/docs/installation/providers/azure.md +++ b/docs/azure.md @@ -1,3 +1,17 @@ +--- +title: "Azure AKS Setup" +description: "Azure configuration with managed PostgreSQL, Key Vault integration, and Workload Identity" +external_links: + - name: "eoapi-k8s Repository" + url: "https://github.com/developmentseed/eoapi-k8s" + - name: "Azure Kubernetes Service Documentation" + url: "https://docs.microsoft.com/en-us/azure/aks/" + - name: "Azure CLI Documentation" + url: "https://docs.microsoft.com/en-us/cli/azure/" + - name: "Azure PostgreSQL Documentation" + url: "https://docs.microsoft.com/en-us/azure/postgresql/" +--- + # Microsoft Azure Setup ## Using Azure Managed PostgreSQL diff --git a/docs/installation/configuration.md b/docs/configuration.md similarity index 91% rename from docs/installation/configuration.md rename to docs/configuration.md index 36d0903f..9a036433 100644 --- a/docs/installation/configuration.md +++ b/docs/configuration.md @@ -1,3 +1,13 @@ +--- +title: "Configuration Options" +description: "Complete reference for Helm values, database types, ingress setup, and service configuration" +external_links: + - name: "eoapi-k8s Repository" + url: "https://github.com/developmentseed/eoapi-k8s" + - name: "Helm Values Documentation" + url: "https://helm.sh/docs/chart_best_practices/values/" +--- + # Configuration Options ## Required Values @@ -116,7 +126,7 @@ raster: ## Deployment Architecture When using default settings, the deployment looks like this: -![](../images/default_architecture.png) +![](./images/default_architecture.png) The deployment includes: - HA PostgreSQL database (via PostgreSQL Operator) @@ -138,7 +148,7 @@ All services include health check endpoints with automatic liveness probes: | Raster API | `/raster/healthz` | HTTP 200, no auth required | | Vector API | `/vector/healthz` | HTTP 200, no auth required | -The Kubernetes deployment templates automatically configure `livenessProbe` settings for regular health checks. See the [deployment template](../../charts/eoapi/templates/services/deployment.yaml) for probe configuration details. +The Kubernetes deployment templates automatically configure `livenessProbe` settings for regular health checks. See the [deployment template](https://github.com/developmentseed/eoapi-k8s/blob/main/charts/eoapi/templates/services/deployment.yaml) for probe configuration details. ## Advanced Configuration diff --git a/docs/docs-config.json b/docs/docs-config.json new file mode 100644 index 00000000..071b5b0b --- /dev/null +++ b/docs/docs-config.json @@ -0,0 +1,54 @@ +{ + "structure": "flat", + "assets_dir": "images", + "external_repo": "https://github.com/developmentseed/eoapi-k8s", + "files": { + "index.md": { "title": "Kubernetes Deployment", "slug": "index" }, + "quick-start.md": { "title": "Quick Start", "slug": "quick-start" }, + "helm-install.md": { "title": "Helm Installation", "slug": "helm-install" }, + "configuration.md": { "title": "Configuration Options", "slug": "configuration" }, + "unified-ingress.md": { "title": "Unified Ingress", "slug": "unified-ingress" }, + "aws-eks.md": { "title": "AWS EKS Setup", "slug": "aws-eks" }, + "gcp-gke.md": { "title": "GCP GKE Setup", "slug": "gcp-gke" }, + "azure.md": { "title": "Azure AKS Setup", "slug": "azure" }, + "manage-data.md": { "title": "Data Management", "slug": "manage-data" }, + "autoscaling.md": { "title": "Autoscaling & Monitoring", "slug": "autoscaling" }, + "stac-auth-proxy.md": { "title": "STAC Auth Proxy", "slug": "stac-auth-proxy" }, + "release.md": { "title": "Release Workflow", "slug": "release" }, + "README.md": { "title": "Documentation Guide", "slug": "docs-readme" } + }, + "nav_structure": [ + { "title": "Overview", "file": "index.md" }, + { "title": "Quick Start", "file": "quick-start.md" }, + { + "title": "Installation", + "children": [ + { "title": "Helm Installation", "file": "helm-install.md" }, + { "title": "Configuration Options", "file": "configuration.md" }, + { "title": "Unified Ingress", "file": "unified-ingress.md" } + ] + }, + { + "title": "Cloud Providers", + "children": [ + { "title": "AWS EKS", "file": "aws-eks.md" }, + { "title": "GCP GKE", "file": "gcp-gke.md" }, + { "title": "Azure AKS", "file": "azure.md" } + ] + }, + { + "title": "Operations", + "children": [ + { "title": "Data Management", "file": "manage-data.md" }, + { "title": "Autoscaling & Monitoring", "file": "autoscaling.md" } + ] + }, + { + "title": "Advanced", + "children": [ + { "title": "STAC Auth Proxy", "file": "stac-auth-proxy.md" }, + { "title": "Release Workflow", "file": "release.md" } + ] + } + ] +} diff --git a/docs/installation/providers/gcp-gke.md b/docs/gcp-gke.md similarity index 86% rename from docs/installation/providers/gcp-gke.md rename to docs/gcp-gke.md index 6d4aa898..703d74f1 100644 --- a/docs/installation/providers/gcp-gke.md +++ b/docs/gcp-gke.md @@ -1,4 +1,18 @@ - # GCP GKE Cluster Setup +--- +title: "GCP GKE Setup" +description: "GKE cluster creation with CSI driver, NGINX ingress, and cert-manager" +external_links: + - name: "eoapi-k8s Repository" + url: "https://github.com/developmentseed/eoapi-k8s" + - name: "Google Cloud Documentation" + url: "https://cloud.google.com/kubernetes-engine/docs" + - name: "gcloud CLI" + url: "https://cloud.google.com/sdk/gcloud" + - name: "Terraform Alternative" + url: "https://github.com/developmentseed/eoapi-k8s-terraform" +--- + +# GCP GKE Cluster Setup This is a verbose walkthrough. It uses `gcloud` and assumes you already have an GCP account and project where you want to run eoapi. We also assume that you have some prerequisites installed including `gcloud`, `kubectl` and `helm`. @@ -109,4 +123,4 @@ helm upgrade --install cert-manager jetstack/cert-manager \ --set installCRDs=true ``` -Now we are ready to install eoapi. See the [eoapi installation instructions](../README.md/#helm-installation) for more details. +Now we are ready to install eoapi. See the [eoapi installation instructions](./helm-install.md) for more details. diff --git a/docs/installation/helm-install.md b/docs/helm-install.md similarity index 81% rename from docs/installation/helm-install.md rename to docs/helm-install.md index b81df5d5..8c8fd9d3 100644 --- a/docs/installation/helm-install.md +++ b/docs/helm-install.md @@ -1,3 +1,15 @@ +--- +title: "Manual Helm Installation" +description: "Step-by-step Helm deployment process with custom configurations" +external_links: + - name: "eoapi-k8s Repository" + url: "https://github.com/developmentseed/eoapi-k8s" + - name: "PostgreSQL Operator Documentation" + url: "https://access.crunchydata.com/documentation/postgres-operator/" + - name: "Helm Charts Repository" + url: "https://devseed.com/eoapi-k8s/" +--- + # Manual Helm Install 0. `eoapi-k8s` depends on the [Crunchydata Postgresql Operator](https://access.crunchydata.com/documentation/postgres-operator/latest/installation/helm). Install that first: diff --git a/docs/index.md b/docs/index.md index 1e5ca6c1..d189ebae 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,3 +1,13 @@ +--- +title: "eoAPI Kubernetes Documentation" +description: "Technical documentation for deploying and operating eoAPI on Kubernetes clusters" +external_links: + - name: "Main eoapi Repository" + url: "https://github.com/developmentseed/eoapi" + - name: "eoapi-k8s Repository" + url: "https://github.com/developmentseed/eoapi-k8s" +--- + # eoAPI Kubernetes Documentation Technical documentation for deploying and operating eoAPI on Kubernetes clusters. @@ -19,41 +29,41 @@ When deployed with default settings, eoAPI provides: ## Quick Start -Please refer to our [quick start guide](./installation/quick-start.md) +Please refer to our [quick start guide](./quick-start.md) ## Installation 1. Set up a Kubernetes cluster using one of the cloud provider guides 2. Install the PostgreSQL Operator dependency -3. Configure your deployment using the [Configuration Options](./installation/configuration.md) -4. Deploy using [Helm Installation](./installation/helm-install.md) instructions -5. Set up monitoring with [Autoscaling & Monitoring](./operations/autoscaling.md) +2. Configure your deployment using the [Configuration Options](./configuration.md) +3. Deploy using [Helm Installation](./helm-install.md) instructions +4. Set up monitoring with [Autoscaling & Monitoring](./autoscaling.md) ## Detailed documenation ### Cloud Provider Guides -- **[AWS EKS Setup](./installation/providers/aws-eks.md)** - Complete EKS cluster setup with OIDC, node autoscaling, EBS CSI, and NGINX ingress -- **[GCP GKE Setup](./installation/providers/gcp-gke.md)** - GKE cluster creation with CSI driver, NGINX ingress, and cert-manager -- **[Azure AKS Setup](./installation/providers/azure.md)** - Azure configuration with managed PostgreSQL, Key Vault integration, and Workload Identity +- **[AWS EKS Setup](./aws-eks.md)** - Complete EKS cluster setup with OIDC, node autoscaling, EBS CSI, and NGINX ingress +- **[GCP GKE Setup](./gcp-gke.md)** - GKE cluster creation with CSI driver, NGINX ingress, and cert-manager +- **[Azure AKS Setup](./azure.md)** - Azure configuration with managed PostgreSQL, Key Vault integration, and Workload Identity ## Installation & Configuration -- **[Configuration Options](./installation/configuration.md)** - Complete reference for Helm values, database types, ingress setup, and service configuration -- **[Manual Helm Installation](./installation/helm-install.md)** - Step-by-step Helm deployment process with custom configurations -- **[Unified Ingress Configuration](./installation/unified-ingress.md)** - NGINX and Traefik ingress setup with TLS and cert-manager integration +- **[Configuration Options](./configuration.md)** - Complete reference for Helm values, database types, ingress setup, and service configuration +- **[Manual Helm Installation](./helm-install.md)** - Step-by-step Helm deployment process with custom configurations +- **[Unified Ingress Configuration](./unified-ingress.md)** - NGINX and Traefik ingress setup with TLS and cert-manager integration ## Database Management -- **[Data Management](./operations/manage-data.md)** - Loading STAC collections and items into PostgreSQL using pypgstac +- **[Data Management](./manage-data.md)** - Loading STAC collections and items into PostgreSQL using pypgstac ## Operations & Monitoring -- **[Autoscaling & Monitoring](./operations/autoscaling.md)** - HPA setup with custom metrics, Grafana dashboards, Prometheus configuration, and load testing +- **[Autoscaling & Monitoring](./autoscaling.md)** - HPA setup with custom metrics, Grafana dashboards, Prometheus configuration, and load testing ## Advanced Features -- **[STAC Auth Proxy Integration](./advanced/stac-auth-proxy.md)** - Service-specific ingress control for authenticated STAC access +- **[STAC Auth Proxy Integration](./stac-auth-proxy.md)** - Service-specific ingress control for authenticated STAC access ## Development & Release -- **[Release Workflow](./advanced/release.md)** - Chart versioning, GitHub releases, and Helm repository publishing process +- **[Release Workflow](./release.md)** - Chart versioning, GitHub releases, and Helm repository publishing process diff --git a/docs/operations/manage-data.md b/docs/manage-data.md similarity index 81% rename from docs/operations/manage-data.md rename to docs/manage-data.md index 7a3a8faa..4876ad2a 100644 --- a/docs/operations/manage-data.md +++ b/docs/manage-data.md @@ -1,3 +1,15 @@ +--- +title: "Data Management" +description: "Loading STAC collections and items into PostgreSQL using pypgstac" +external_links: + - name: "eoapi-k8s Repository" + url: "https://github.com/developmentseed/eoapi-k8s" + - name: "pypgstac Documentation" + url: "https://github.com/stac-utils/pypgstac" + - name: "STAC Specification" + url: "https://stacspec.org/" +--- + # Data management eoAPI-k8s provides a basic data ingestion process that consist of manual operations on the components of the stack. diff --git a/docs/installation/quick-start.md b/docs/quick-start.md similarity index 88% rename from docs/installation/quick-start.md rename to docs/quick-start.md index f36f693c..f2e58021 100644 --- a/docs/installation/quick-start.md +++ b/docs/quick-start.md @@ -1,3 +1,13 @@ +--- +title: "Quick Start" +description: "Fast installation guide for eoAPI Kubernetes deployment" +external_links: + - name: "eoapi-k8s Repository" + url: "https://github.com/developmentseed/eoapi-k8s" + - name: "Helm Documentation" + url: "https://helm.sh/docs/" +--- + # Quick Start ## Prerequisites diff --git a/docs/advanced/release.md b/docs/release.md similarity index 78% rename from docs/advanced/release.md rename to docs/release.md index 017dbbcd..2fa9118b 100644 --- a/docs/advanced/release.md +++ b/docs/release.md @@ -1,3 +1,15 @@ +--- +title: "Release Workflow" +description: "Chart versioning, GitHub releases, and Helm repository publishing process" +external_links: + - name: "eoapi-k8s Repository" + url: "https://github.com/developmentseed/eoapi-k8s" + - name: "Semantic Versioning" + url: "https://semver.org/" + - name: "Helm Chart Best Practices" + url: "https://helm.sh/docs/chart_best_practices/" +--- + ### Release Workflow 1. PRs that include changes in the `charts/ || || ` charts are manually required to consider diff --git a/docs/advanced/stac-auth-proxy.md b/docs/stac-auth-proxy.md similarity index 94% rename from docs/advanced/stac-auth-proxy.md rename to docs/stac-auth-proxy.md index 1fbfacda..0c1df345 100644 --- a/docs/advanced/stac-auth-proxy.md +++ b/docs/stac-auth-proxy.md @@ -1,3 +1,13 @@ +--- +title: "STAC Auth Proxy Integration" +description: "Service-specific ingress control for authenticated STAC access" +external_links: + - name: "eoapi-k8s Repository" + url: "https://github.com/developmentseed/eoapi-k8s" + - name: "STAC Auth Proxy" + url: "https://github.com/developmentseed/stac-auth-proxy" +--- + # STAC Auth Proxy Integration with eoAPI-K8S ## Solution Overview diff --git a/docs/installation/unified-ingress.md b/docs/unified-ingress.md similarity index 90% rename from docs/installation/unified-ingress.md rename to docs/unified-ingress.md index ebf1b6e1..6a41b78e 100644 --- a/docs/installation/unified-ingress.md +++ b/docs/unified-ingress.md @@ -1,3 +1,17 @@ +--- +title: "Unified Ingress Configuration" +description: "NGINX and Traefik ingress setup with TLS and cert-manager integration" +external_links: + - name: "eoapi-k8s Repository" + url: "https://github.com/developmentseed/eoapi-k8s" + - name: "NGINX Ingress Controller" + url: "https://kubernetes.github.io/ingress-nginx/" + - name: "Traefik Documentation" + url: "https://doc.traefik.io/traefik/" + - name: "cert-manager" + url: "https://cert-manager.io/" +--- + # Unified Ingress Configuration This document describes the unified ingress approach implemented in the eoAPI Helm chart. diff --git a/scripts/generate-portable-docs.sh b/scripts/generate-portable-docs.sh new file mode 100755 index 00000000..5e7f903d --- /dev/null +++ b/scripts/generate-portable-docs.sh @@ -0,0 +1,103 @@ +#!/bin/bash +# Generate documentation package for external consumption + +set -e + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +PROJECT_ROOT="$(dirname "$SCRIPT_DIR")" +DOCS_DIR="$PROJECT_ROOT/docs" +OUTPUT_DIR="$PROJECT_ROOT/dist/docs-portable" +REPO_URL="https://github.com/developmentseed/eoapi-k8s" + +echo "Generating portable documentation package..." + +# Clean and create output directory +rm -rf "$OUTPUT_DIR" +mkdir -p "$OUTPUT_DIR" + +# Process markdown files +find "$DOCS_DIR" -name "*.md" -type f | while read -r file; do + # Get relative path from docs directory + rel_path=$(realpath --relative-to="$DOCS_DIR" "$file") + output_file="$OUTPUT_DIR/$(basename "$file")" + + echo "Processing: $rel_path -> $(basename "$file")" + + # Process file to make links external-friendly + sed \ + -e "s|](\\./|]($REPO_URL/blob/main/docs/|g" \ + -e "s|](\\.\\./*|]($REPO_URL/blob/main/|g" \ + -e "s|](docs/|]($REPO_URL/blob/main/docs/|g" \ + -e "s|](images/|]($REPO_URL/blob/main/docs/images/|g" \ + -e "s|](\\./images/|]($REPO_URL/blob/main/docs/images/|g" \ + "$file" > "$output_file" +done + +# Copy assets directory +if [ -d "$DOCS_DIR/images" ]; then + echo "Copying images directory..." + cp -r "$DOCS_DIR/images" "$OUTPUT_DIR/" +fi + +# Copy includes directory if it exists +if [ -d "$DOCS_DIR/_includes" ]; then + echo "Copying _includes directory..." + cp -r "$DOCS_DIR/_includes" "$OUTPUT_DIR/" +fi + +# Copy docs config file if it exists +if [ -f "$DOCS_DIR/docs-config.json" ]; then + echo "Copying docs-config.json..." + cp "$DOCS_DIR/docs-config.json" "$OUTPUT_DIR/" +fi + +# Generate index file with all documentation +cat > "$OUTPUT_DIR/README.md" << EOF +# eoAPI Kubernetes Documentation (Portable) + +This is a portable version of the eoAPI Kubernetes documentation, generated from the [eoapi-k8s repository]($REPO_URL). + +## Available Documentation + +$(find "$OUTPUT_DIR" -name "*.md" -not -name "README.md" | sort | while read -r file; do + filename=$(basename "$file" .md) + title=$(grep "^# " "$file" | head -1 | sed 's/^# //' || echo "$filename") + echo "- [$title](./$filename.md)" +done) + +## Source Repository + +For the latest version of this documentation, visit the [eoapi-k8s repository]($REPO_URL). + +Generated on: $(date -u +"%Y-%m-%d %H:%M:%S UTC") +EOF + +# Create manifest file +cat > "$OUTPUT_DIR/manifest.json" << EOF +{ + "generated_at": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")", + "source_repo": "$REPO_URL", + "version": "portable", + "files": [ +$(find "$OUTPUT_DIR" -name "*.md" | sort | while read -r file; do + filename=$(basename "$file") + size=$(wc -c < "$file") + echo " {\"name\": \"$filename\", \"size\": $size}" +done | paste -sd ',' -) + ] +} +EOF + +echo "Portable documentation generated in: $OUTPUT_DIR" +echo "Files created:" +find "$OUTPUT_DIR" -type f | sort | sed 's|^| - |' + +# Optionally create a tarball +if command -v tar >/dev/null 2>&1; then + tarball="$PROJECT_ROOT/dist/eoapi-k8s-docs-portable.tar.gz" + echo "Creating tarball: $tarball" + (cd "$PROJECT_ROOT/dist" && tar -czf "eoapi-k8s-docs-portable.tar.gz" docs-portable/) + echo "Tarball created: $tarball" +fi + +echo "Done!" From 4d3a9b085b3bc3bcbbd27b02dc17b12f09c0a1cd Mon Sep 17 00:00:00 2001 From: Felix Delattre Date: Mon, 27 Oct 2025 10:12:37 +0100 Subject: [PATCH 2/2] foo --- .github/workflows/validate-docs-links.yml | 31 +++++++++++++++++------ 1 file changed, 23 insertions(+), 8 deletions(-) diff --git a/.github/workflows/validate-docs-links.yml b/.github/workflows/validate-docs-links.yml index 9c17e2c7..0cf17d00 100644 --- a/.github/workflows/validate-docs-links.yml +++ b/.github/workflows/validate-docs-links.yml @@ -19,10 +19,10 @@ jobs: - name: Setup Node.js uses: actions/setup-node@v4 with: - node-version: '18' + node-version: '20' - name: Install markdown-link-check - run: npm install -g markdown-link-check + run: npm install -g markdown-link-check@3.11.2 - name: Create markdown-link-check config run: | @@ -67,6 +67,10 @@ jobs: broken_links_found=0 while IFS= read -r -d '' file; do + # Skip files that don't contain any internal links + if ! grep -q "](\./" "$file" 2>/dev/null; then + continue + fi echo "Checking internal links in: $file" # Check for broken relative links @@ -101,25 +105,36 @@ jobs: run: | echo "Validating external links..." find docs -name "*.md" -type f | while read -r file; do + # Skip files that don't contain any links + if ! grep -q "](http" "$file" 2>/dev/null; then + echo "ℹ️ Skipping $file (no external links found)" + continue + fi echo "Checking external links in: $file" - markdown-link-check "$file" --config .markdown-link-check.json || echo "Some external links failed in $file" + # Use timeout to avoid hanging and make failures non-blocking + timeout 30 markdown-link-check "$file" --config .markdown-link-check.json 2>/dev/null || \ + echo "⚠️ External link validation failed for $file (non-blocking)" done + echo "✅ External link validation completed" - name: Check for consistent link patterns run: | echo "Checking for inconsistent link patterns..." inconsistent_found=false - # Check for bad patterns - if find docs -name "*.md" -exec grep -l "](docs/" {} \;; then + # Check for internal docs/ prefix links (exclude external URLs) + internal_docs_links=$(find docs -name "*.md" -type f -exec grep -H "](docs/" {} \; 2>/dev/null | grep -v "https\?://[^)]*docs/" || true) + if [[ -n "$internal_docs_links" ]]; then echo "❌ Found links using 'docs/' prefix - use relative paths instead" - find docs -name "*.md" -exec grep -Hn "](docs/" {} \; + echo "$internal_docs_links" inconsistent_found=true fi - if find docs -name "*.md" -exec grep -l "](\.\./" {} \;; then + # Check for ../ patterns + dotdot_links=$(find docs -name "*.md" -type f -exec grep -Hn "](\.\./" {} \; 2>/dev/null || true) + if [[ -n "$dotdot_links" ]]; then echo "❌ Found links using '../' - use relative paths from docs root instead" - find docs -name "*.md" -exec grep -Hn "](\.\./" {} \; + echo "$dotdot_links" inconsistent_found=true fi