From 7682efa50ce114970c63e30d7dfbebde55d5dc76 Mon Sep 17 00:00:00 2001
From: Aric Camarata <aric.camarata@gmail.com>
Date: Sun, 8 Mar 2026 17:14:26 -0400
Subject: [PATCH] docs: add wiki pages and wiki-sync workflow

---
 .github/workflows/wiki-sync.yml | 42 +++++++++++++++++++
 .wiki/API-Reference.md          | 72 +++++++++++++++++++++++++++++++++
 .wiki/Home.md                   | 29 +++++++++++++
 3 files changed, 143 insertions(+)
 create mode 100644 .github/workflows/wiki-sync.yml
 create mode 100644 .wiki/API-Reference.md
 create mode 100644 .wiki/Home.md

diff --git a/.github/workflows/wiki-sync.yml b/.github/workflows/wiki-sync.yml
new file mode 100644
index 0000000..974c6c6
--- /dev/null
+++ b/.github/workflows/wiki-sync.yml
@@ -0,0 +1,42 @@
+name: Sync Wiki
+
+on:
+  push:
+    branches: [main]
+    paths: [".wiki/**"]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Checkout wiki
+        id: clone_wiki
+        run: |
+          if git clone "https://x-access-token:${{ github.token }}@github.com/${{ github.repository }}.wiki.git" .wiki-remote 2>&1; then
+            echo "wiki_exists=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "wiki_exists=false" >> "$GITHUB_OUTPUT"
+            echo "Wiki not yet initialized — skipping sync. Initialize via GitHub web UI first."
+          fi
+
+      - name: Sync wiki pages
+        if: steps.clone_wiki.outputs.wiki_exists == 'true'
+        run: |
+          cp .wiki/*.md .wiki-remote/
+          cd .wiki-remote
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add -A
+          if git diff --cached --quiet; then
+            echo "No wiki changes to commit"
+          else
+            git commit -m "Sync wiki from repo"
+            git push origin HEAD:master
+          fi
diff --git a/.wiki/API-Reference.md b/.wiki/API-Reference.md
new file mode 100644
index 0000000..224b455
--- /dev/null
+++ b/.wiki/API-Reference.md
@@ -0,0 +1,72 @@
+# API Reference
+
+## getSpa
+
+```dart
+SpaResult getSpa(
+  DateTime date,
+  double latitude,
+  double longitude,
+  double timezone, {
+  double elevation = 0,
+  double pressure = 1013,
+  double temperature = 15,
+  double deltaT = 67,
+  List<double> customAngles = const [],
+})
+```
+
+Computes solar position for a given location and moment.
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `date` | `DateTime` | required | UTC date and time |
+| `latitude` | `double` | required | Degrees (-90 to 90) |
+| `longitude` | `double` | required | Degrees (-180 to 180) |
+| `timezone` | `double` | required | Hours from UTC |
+| `elevation` | `double` | 0 | Meters above sea level |
+| `pressure` | `double` | 1013 | Atmospheric pressure (mbar) |
+| `temperature` | `double` | 15 | Temperature (Celsius) |
+| `deltaT` | `double` | 67 | TT - UT1 (seconds) |
+| `customAngles` | `List<double>` | [] | Zenith angles for custom rise/set computation |
+
+### SpaResult fields
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `zenith` | `double` | Solar zenith angle (degrees) |
+| `azimuth` | `double` | Solar azimuth angle (degrees, clockwise from north) |
+| `sunrise` | `double` | Sunrise in fractional hours (local time) |
+| `solarNoon` | `double` | Solar noon in fractional hours (local time) |
+| `sunset` | `double` | Sunset in fractional hours (local time) |
+| `angles` | `List<SpaAngleResult>` | Rise/set pairs for each entry in `customAngles` |
+
+### SpaAngleResult fields
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `zenith` | `double` | The requested zenith angle |
+| `sunrise` | `double` | Rise time in fractional hours for this zenith |
+| `sunset` | `double` | Set time in fractional hours for this zenith |
+
+### Custom zenith angles
+
+Pass any solar zenith angles to get rise/set times at those angles. Standard civil/nautical/astronomical twilight angles are 96, 102, and 108 degrees respectively. Prayer time implementations use this to calculate Fajr and Isha.
+
+```dart
+final result = getSpa(
+  DateTime.utc(2024, 3, 15, 12, 0, 0),
+  40.7128, -74.0060, -5.0,
+  customAngles: [96.0, 102.0, 108.0],
+);
+
+for (final angle in result.angles) {
+  print('${angle.zenith}: rise ${angle.sunrise}, set ${angle.sunset}');
+}
+```
+
+---
+
+[Home](Home)
diff --git a/.wiki/Home.md b/.wiki/Home.md
new file mode 100644
index 0000000..e101c2d
--- /dev/null
+++ b/.wiki/Home.md
@@ -0,0 +1,29 @@
+# nrel_spa
+
+NREL Solar Position Algorithm for Dart and Flutter. Calculates solar zenith, azimuth, sunrise, sunset, and solar noon for any location and time. Pure Dart, zero dependencies.
+
+Accurate to +/- 0.0003 degrees. Based on Reda & Andreas (2004), NREL/TP-560-34302.
+
+## Quick Start
+
+```dart
+import 'package:nrel_spa/nrel_spa.dart';
+
+final result = getSpa(
+  DateTime.utc(2024, 3, 15, 17, 0, 0),
+  40.7128,  // latitude
+  -74.0060, // longitude
+  -5.0,     // UTC offset (EST)
+);
+
+print('Zenith:     ${result.zenith.toStringAsFixed(4)}');
+print('Azimuth:    ${result.azimuth.toStringAsFixed(4)}');
+print('Sunrise:    ${result.sunrise.toStringAsFixed(4)} h');
+print('Solar Noon: ${result.solarNoon.toStringAsFixed(4)} h');
+print('Sunset:     ${result.sunset.toStringAsFixed(4)} h');
+```
+
+## Pages
+
+- [API Reference](API-Reference) — Full function and type reference
+- [Architecture](Architecture) — Algorithm design and implementation notes