refactor: documentation structure. (#318)

Author: pantierra

.github/workflows/ci.yml

@@ -114,3 +114,47 @@ jobs:
         run: |
           helm uninstall "$RELEASE_NAME" -n eoapi || true
           kubectl delete namespace eoapi || true
+  validate-docs:
+    name: Validate documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Check internal links
+        run: |
+          broken=0
+          find docs -name "*.md" | while read -r file; do
+            if grep -q "](\./" "$file" 2>/dev/null; then
+              grep -n "](\./" "$file" | while IFS=: read -r line link; do
+                path=$(echo "$link" | sed -n 's/.*](\.\///; s/).*//p')
+                if [[ "$path" == images/* ]]; then
+                  full="docs/$path"
+                else
+                  full="docs/$path"
+                fi
+                if [[ ! -e "$full" ]]; then
+                  echo "❌ $file:$line -> $path"
+                  broken=1
+                fi
+              done
+            fi
+          done
+          exit $broken
+
+      - name: Check external links
+        run: |
+          npm install -g markdown-link-check@3.11.2
+          echo '{"timeout":"10s","retryCount":2,"aliveStatusCodes":[200,301,302,403,999]}' > .mlc.json
+          find docs -name "*.md" -exec timeout 30 markdown-link-check {} --config .mlc.json \; || true
+
+      - name: Check frontmatter
+        run: |
+          missing=0
+          find docs -name "*.md" -not -path "docs/_includes/*" | while read -r file; do
+            head -1 "$file" | grep -q "^---$" || { echo "❌ Missing frontmatter: $file"; missing=1; }
+          done
+          exit $missing

.gitignore

@@ -4,5 +4,7 @@
 charts/config.yaml
 charts/eoapi/charts/*.tgz
 config_ingress.yaml
+dist
+site
 __pycache__
 CLAUDE.md

CHANGELOG.md

@@ -15,6 +15,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Unified local cluster management with `CLUSTER_TYPE` variable
 - Improved CI and local debugging; added debug-deployment.sh script
 - Added knative in CI to test eoapi-notifier.
+- Restructured docs with flattened structure and added portable documentation generation
 
 ## [0.7.12] - 2025-10-17
 

Makefile

@@ -7,7 +7,7 @@ TEST_SCRIPT := ./scripts/test.sh
 # Default cluster type (can be overridden)
 CLUSTER_TYPE ?= minikube
 
-.PHONY: help deploy clean tests integration lint validate-schema
+.PHONY: help deploy clean tests integration lint validate-schema docs serve-docs
 .DEFAULT_GOAL := help
 
 help:
@@ -30,6 +30,8 @@ help:
 	@echo "QUALITY:"
 	@echo "  lint            Run linting and code quality checks"
 	@echo "  validate-schema Validate Helm schemas"
+	@echo "  docs            Generate portable documentation package"
+	@echo "  serve-docs      Serve docs with mkdocs at http://localhost:8000"
 	@echo ""
 	@echo "VARIABLES:"
 	@echo "  CLUSTER_TYPE    Local cluster type: minikube or k3s (default: minikube)"
@@ -104,3 +106,13 @@ validate-schema:
 
 ingest:
 	@./scripts/ingest.sh
+
+docs:
+	@command -v mkdocs >/dev/null 2>&1 || { echo "❌ mkdocs required. Run: pip install mkdocs-material"; exit 1; }
+	@echo "📚 Building documentation with mkdocs"
+	@mkdocs build
+
+serve-docs: docs
+	@echo "📚 Serving docs with mkdocs at http://localhost:8000"
+	@echo "Press Ctrl+C to stop"
+	@mkdocs serve --dev-addr localhost:8000

README.md

@@ -28,11 +28,11 @@
 
 ### Get started
 
-* [Quick start guide](./docs/installation/quick-start.md)
+* [Quick start guide](./docs/quick-start.md)
 
 ### `eoAPI-k8s` documentation
 
-* [Overview of docs](./docs/index.md)
+* [Overview of docs](https://eoapi.dev/deployment/kubernetes)
 
 ### General eoAPI documentation
 * [eoapi.dev](https://eoapi.dev) website.

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
 

docs/_includes/repository-links.md

@@ -0,0 +1,8 @@
+<!-- Reusable repository references -->
+[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/

docs/operations/autoscaling.md renamed to docs/autoscaling.md

@@ -1,11 +1,25 @@
+---
+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
 your data volume, data usage patterns, bottlenecks (such as the database) among many, many other things. Load testing,
 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 `<release-name>-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
 

docs/installation/providers/aws-eks.md renamed to 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`.

docs/installation/providers/azure.md renamed to 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