Skip to content

Commit f8d84c8

Browse files
pantierrapantierra
committed
Refactor: documentation structure.
1 parent 35a6adb commit f8d84c8

18 files changed

+636
-26
lines changed

‎.github/workflows/validate-docs-links.yml‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
name: Validate Documentation Links
2+
3+
on:
4+
push:
5+
branches: [ main, master ]
6+
paths: [ 'docs/**/*.md' ]
7+
pull_request:
8+
branches: [ main, master ]
9+
paths: [ 'docs/**/*.md' ]
10+
11+
jobs:
12+
validate-links:
13+
runs-on: ubuntu-latest
14+
15+
steps:
16+
- name: Checkout repository
17+
uses: actions/checkout@v4
18+
19+
- name: Setup Node.js
20+
uses: actions/setup-node@v4
21+
with:
22+
node-version: '18'
23+
24+
- name: Install markdown-link-check
25+
run: npm install -g markdown-link-check
26+
27+
- name: Create markdown-link-check config
28+
run: |
29+
cat > .markdown-link-check.json << 'EOF'
30+
{
31+
"ignorePatterns": [
32+
{
33+
"pattern": "^https://github.com/developmentseed/eoapi-k8s"
34+
},
35+
{
36+
"pattern": "localhost"
37+
},
38+
{
39+
"pattern": "127.0.0.1"
40+
}
41+
],
42+
"replacementPatterns": [
43+
{
44+
"pattern": "^./",
45+
"replacement": "{{BASEURL}}/"
46+
}
47+
],
48+
"httpHeaders": [
49+
{
50+
"urls": ["https://github.com"],
51+
"headers": {
52+
"Accept": "text/html"
53+
}
54+
}
55+
],
56+
"timeout": "20s",
57+
"retryOn429": true,
58+
"retryCount": 3,
59+
"fallbackRetryDelay": "30s",
60+
"aliveStatusCodes": [200, 206, 301, 302, 403, 999]
61+
}
62+
EOF
63+
64+
- name: Validate internal links
65+
run: |
66+
echo "Checking internal link patterns..."
67+
broken_links_found=0
68+
69+
while IFS= read -r -d '' file; do
70+
echo "Checking internal links in: $file"
71+
72+
# Check for broken relative links
73+
while IFS=: read -r line_num link; do
74+
# Extract the link path
75+
link_path=$(echo "$link" | sed -n 's/.*](\.\///; s/).*//p')
76+
77+
# Check if it's an image link
78+
if [[ "$link_path" == images/* ]]; then
79+
full_path="docs/$link_path"
80+
else
81+
full_path="docs/$link_path"
82+
fi
83+
84+
if [[ ! -e "$full_path" ]]; then
85+
echo "❌ Broken internal link in $file:$line_num -> $link_path (resolved to: $full_path)"
86+
broken_links_found=1
87+
else
88+
echo "✅ Valid internal link: $link_path"
89+
fi
90+
done < <(grep -n "](\./" "$file" || true)
91+
done < <(find docs -name "*.md" -type f -print0)
92+
93+
if [[ $broken_links_found -eq 1 ]]; then
94+
echo "❌ Found broken internal links!"
95+
exit 1
96+
else
97+
echo "✅ All internal links are valid!"
98+
fi
99+
100+
- name: Validate external links
101+
run: |
102+
echo "Validating external links..."
103+
find docs -name "*.md" -type f | while read -r file; do
104+
echo "Checking external links in: $file"
105+
markdown-link-check "$file" --config .markdown-link-check.json || echo "Some external links failed in $file"
106+
done
107+
108+
- name: Check for consistent link patterns
109+
run: |
110+
echo "Checking for inconsistent link patterns..."
111+
inconsistent_found=false
112+
113+
# Check for bad patterns
114+
if find docs -name "*.md" -exec grep -l "](docs/" {} \;; then
115+
echo "❌ Found links using 'docs/' prefix - use relative paths instead"
116+
find docs -name "*.md" -exec grep -Hn "](docs/" {} \;
117+
inconsistent_found=true
118+
fi
119+
120+
if find docs -name "*.md" -exec grep -l "](\.\./" {} \;; then
121+
echo "❌ Found links using '../' - use relative paths from docs root instead"
122+
find docs -name "*.md" -exec grep -Hn "](\.\./" {} \;
123+
inconsistent_found=true
124+
fi
125+
126+
if [[ "$inconsistent_found" == "true" ]]; then
127+
echo "❌ Found inconsistent link patterns!"
128+
echo "Use these patterns instead:"
129+
echo " - [Installation Guide](./installation.md)"
130+
echo " - [AWS Setup](./aws-eks.md)"
131+
echo " - [Images](./images/diagram.png)"
132+
exit 1
133+
else
134+
echo "✅ All link patterns are consistent!"
135+
fi
136+
137+
- name: Validate frontmatter
138+
run: |
139+
echo "Checking that all markdown files have frontmatter..."
140+
missing_frontmatter_found=0
141+
142+
while IFS= read -r -d '' file; do
143+
if ! head -1 "$file" | grep -q "^---$"; then
144+
echo "❌ Missing frontmatter in: $file"
145+
missing_frontmatter_found=1
146+
fi
147+
done < <(find docs -name "*.md" -not -path "docs/_includes/*" -type f -print0)
148+
149+
if [[ $missing_frontmatter_found -eq 1 ]]; then
150+
echo "❌ Some files are missing frontmatter!"
151+
echo "Add frontmatter like:"
152+
echo "---"
153+
echo "title: \"Page Title\""
154+
echo "description: \"Page description\""
155+
echo "external_links:"
156+
echo " - name: \"Link Name\""
157+
echo " url: \"https://example.com\""
158+
echo "---"
159+
exit 1
160+
else
161+
echo "✅ All markdown files have frontmatter!"
162+
fi

‎Makefile‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ HELM_REPO_URL=https://devseed.com/eoapi-k8s/
55
HELM_CHART_NAME=eoapi/eoapi
66
PGO_CHART_VERSION=5.7.4
77

8-
.PHONY: all deploy minikube ingest tests integration lint validate-schema help
8+
.PHONY: all deploy minikube ingest tests integration lint validate-schema docs help
99

1010
# Default target
1111
all: deploy
@@ -25,6 +25,11 @@ minikube:
2525
@echo "eoAPI is now available at:"
2626
@minikube service ingress-nginx-controller -n ingress-nginx --url | head -n 1
2727

28+
docs:
29+
@echo "Generating portable documentation package."
30+
@command -v bash >/dev/null 2>&1 || { echo "bash is required but not installed"; exit 1; }
31+
@./scripts/generate-portable-docs.sh
32+
2833
ingest:
2934
@echo "Ingesting STAC collections and items into the database."
3035
@command -v bash >/dev/null 2>&1 || { echo "bash is required but not installed"; exit 1; }

‎docs/README.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# eoAPI Kubernetes Documentation
2+
3+
This directory contains the complete documentation for eoAPI Kubernetes deployments.
4+
5+
## Structure
6+
7+
We use a **flat directory structure** for better portability and consistency:
8+
9+
```
10+
docs/
11+
├── index.md # Main documentation overview
12+
├── quick-start.md # Fast installation guide
13+
├── helm-install.md # Manual Helm installation
14+
├── configuration.md # Configuration options reference
15+
├── unified-ingress.md # Ingress setup guide
16+
├── aws-eks.md # AWS EKS cluster setup
17+
├── gcp-gke.md # GCP GKE cluster setup
18+
├── azure.md # Azure AKS setup
19+
├── manage-data.md # Data management guide
20+
├── autoscaling.md # Monitoring and autoscaling
21+
├── stac-auth-proxy.md # STAC authentication proxy
22+
├── release.md # Release workflow
23+
├── images/ # Documentation images
24+
├── _includes/ # Reusable content snippets
25+
└── README.md # This file
26+
```
27+
28+
## Link Standards
29+
30+
All documentation uses **consistent relative links** from the docs root:
31+
32+
✅ **Correct patterns:**
33+
```markdown
34+
[Installation Guide](./helm-install.md)
35+
[AWS Setup](./aws-eks.md)
36+
[Images](./images/default_architecture.png)
37+
```
38+
39+
❌ **Avoid these patterns:**
40+
```markdown
41+
[Bad](docs/installation.md)
42+
[Bad](./docs/installation.md)
43+
[Bad](../installation.md)
44+
```
45+
46+
## Frontmatter Format
47+
48+
Every markdown file includes standardized frontmatter:
49+
50+
```yaml
51+
---
52+
title: "Page Title"
53+
description: "Brief page description"
54+
external_links:
55+
- name: "Link Name"
56+
url: "https://example.com"
57+
---
58+
```
59+
60+
## Portable Documentation
61+
62+
Generate a standalone documentation package:
63+
64+
```bash
65+
# Generate portable docs
66+
make docs
67+
68+
# Or run directly
69+
./scripts/generate-portable-docs.sh
70+
```
71+
72+
This creates `dist/docs-portable/` with:
73+
- All markdown files with external-friendly links
74+
- Images and assets copied
75+
- Manifest and README for external consumption
76+
- Optional tarball for distribution
77+
78+
## Link Validation
79+
80+
GitHub Actions automatically validate:
81+
- ✅ Internal link integrity
82+
- ✅ Consistent link patterns
83+
- ✅ Frontmatter presence
84+
- ⚠️ External link availability
85+
86+
## Configuration
87+
88+
The `docs/docs-config.json` file defines the documentation structure for external tools:
89+
90+
```json
91+
{
92+
"structure": "flat",
93+
"assets_dir": "images",
94+
"external_repo": "https://github.com/developmentseed/eoapi-k8s",
95+
"files": { ... },
96+
"nav_structure": [ ... ]
97+
}
98+
```
99+
100+
## Reusable Content
101+
102+
Common links and snippets are stored in `_includes/repository-links.md`:
103+
104+
```markdown
105+
[Main eoapi Repository]: https://github.com/developmentseed/eoapi
106+
[eoapi-k8s Repository]: https://github.com/developmentseed/eoapi-k8s
107+
[Report Issues]: https://github.com/developmentseed/eoapi-k8s/issues
108+
```
109+
110+
## Contributing
111+
112+
When editing documentation:
113+
114+
1. **Use flat structure** - all `.md` files in docs root
115+
2. **Follow link standards** - relative paths from docs root
116+
3. **Include frontmatter** - title, description, external_links
117+
4. **Test locally** - run `make docs` to verify portable generation
118+
5. **Validate links** - GitHub Actions will check on PR
119+
120+
## Navigation Flow
121+
122+
```
123+
index.md → quick-start.md → helm-install.md → configuration.md
124+
↓
125+
Cloud Providers: aws-eks.md | gcp-gke.md | azure.md
126+
↓
127+
Operations: manage-data.md → autoscaling.md
128+
↓
129+
Advanced: stac-auth-proxy.md → release.md
130+
```
131+
132+
This structure ensures documentation is maintainable, portable, and consistent across different consumption contexts.

‎docs/_includes/repository-links.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
<!-- Reusable repository references -->
2+
[Main eoapi Repository]: https://github.com/developmentseed/eoapi
3+
[eoapi-k8s Repository]: https://github.com/developmentseed/eoapi-k8s
4+
[Report Issues]: https://github.com/developmentseed/eoapi-k8s/issues
5+
[eoAPI Documentation]: https://eoapi.dev/
6+
[Helm Charts]: https://github.com/developmentseed/eoapi-k8s/tree/main/charts
7+
[PostgreSQL Operator]: https://access.crunchydata.com/documentation/postgres-operator/
8+
[Kubernetes Documentation]: https://kubernetes.io/docs/

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

Lines changed: 21 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,17 @@
1+
---
2+
title: "Autoscaling & Monitoring"
3+
description: "HPA setup with custom metrics, Grafana dashboards, Prometheus configuration, and load testing"
4+
external_links:
5+
- name: "eoapi-k8s Repository"
6+
url: "https://github.com/developmentseed/eoapi-k8s"
7+
- name: "Kubernetes HPA Documentation"
8+
url: "https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/"
9+
- name: "Prometheus Documentation"
10+
url: "https://prometheus.io/docs/"
11+
- name: "Grafana Documentation"
12+
url: "https://grafana.com/docs/"
13+
---
14+
115
# Autoscaling / Monitoring / Observability
216

317
Autoscaling is both art and science. To test out your application's autoscaling requirements you often need to consider
@@ -17,7 +31,7 @@ might want to read through the verbose walkthrough material below to familiarize
1731

1832
## Helm Install `eoapi-support`
1933

20-
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
34+
The following instructions assume you've gone through the [AWS](./aws-eks.md) or [GCP](./gcp-gke.md) cluster set up
2135
and installed the `eoapi` chart.
2236

2337

@@ -99,9 +113,9 @@ manual step that cannot be automated
99113

100114
---
101115

102-
### Review [Default Configuration and Options](../installation/configuration.md)
116+
### Review [Default Configuration and Options](./configuration.md)
103117

104-
[This document](../installation/configuration.md) will explain the differences in the `autoscaling` block for each service:
118+
[This document](./configuration.md) will explain the differences in the `autoscaling` block for each service:
105119

106120
```yaml
107121
autoscaling:
@@ -199,15 +213,15 @@ with the `release` name we installed the chart with below `<release-name>-grafan
199213

200214
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:
201215

202-
![Grafana Datasource Configuration](../images/datasource.png)
216+
![Grafana Datasource Configuration](./images/datasource.png)
203217

204218
You can then view the main eoAPI dashboard:
205219

206-
![](../images/gfdashboard.png)
220+
![](./images/gfdashboard.png)
207221

208222
To add additional custom dashboards, you can use the dashboard import functionality:
209223

210-
![Adding Custom Grafana Dashboards](../images/add-grafana-dashboard.png)
224+
![Adding Custom Grafana Dashboards](./images/add-grafana-dashboard.png)
211225

212226
### Install or Upgrade Autoscaling Changes to `eoapi` Chart
213227

@@ -361,7 +375,7 @@ that you're deploying using `ingress.className: "nginx"`.
361375

362376
4. **Monitor autoscaling in Grafana** - Go back to your Grafana dashboard and watch your services autoscale for the endpoints you're hitting:
363377

364-
![Grafana Autoscaling Dashboard](../images/grafanaautoscale.png)
378+
![Grafana Autoscaling Dashboard](./images/grafanaautoscale.png)
365379

366380
### Load Testing Best Practices
367381

0 commit comments

Comments
 (0)