mirror of
https://github.com/acamarata/nrel-spa-dart.git
synced 2026-06-30 19:04:24 +00:00
docs: add wiki pages and wiki-sync workflow
This commit is contained in:
Aric Camarata
parent
ac6a87c18a
commit
7682efa50c
3 changed files with 143 additions and 0 deletions
42
.github/workflows/wiki-sync.yml
vendored
Normal file
42
.github/workflows/wiki-sync.yml
vendored
Normal file
|
|
@ -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
|
||||
72
.wiki/API-Reference.md
Normal file
72
.wiki/API-Reference.md
Normal file
|
|
@ -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)
|
||||
29
.wiki/Home.md
Normal file
29
.wiki/Home.md
Normal file
|
|
@ -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
|
||||
Loading…
Reference in a new issue