Merge pull request #59 from JuliaAstro/readme

Update docs/readme

Author: langestefan

CITATION.cff

@@ -10,8 +10,8 @@ authors:
 repository-code: https://github.com/JuliaAstro/SolarPosition.jl
 url: https://juliaastro.github.io/SolarPosition.jl/
 license: MIT
-version: 0.3.2
-date-released: 2025-12-20
+version: 0.4.0
+date-released: 2026-01-05
 abstract: >-
   SolarPosition.jl provides a simple, unified interface to a collection
   of validated solar position algorithms written in pure Julia.

README.md

@@ -33,12 +33,15 @@ correctness of the algorithm implementations.
 ## Example Usage
 
 ```julia
-julia> using SolarPosition, Dates
+julia> using SolarPosition, Dates, TimeZones
 
 # define observer location (latitude, longitude, altitude in meters)
 julia> obs = Observer(52.35888, 4.88185, 100.0)  # Van Gogh Museum, Amsterdam
 Observer(latitude=52.35888°, longitude=4.88185°, altitude=100.0m)
 
+julia> tz = TimeZone("Europe/Brussels")
+Europe/Brussels (UTC+1/UTC+2)
+
 # a few hours of timestamps
 julia> times = collect(DateTime(2023, 6, 21, 10):Hour(1):DateTime(2023, 6, 21, 15));
 
@@ -53,6 +56,33 @@ julia> positions = solar_position(obs, times)
  SolPos(azimuth=251.77304757136397°, elevation=42.790197455865076°, zenith=47.209802544134924°)
 ```
 
+### Sunrise and Sunset Calculations
+
+Calculate sunrise, sunset, and solar noon for a specific date with timezone:
+
+```julia
+julia> result = transit_sunrise_sunset(obs, ZonedDateTime(2023, 6, 21, tz))
+TransitSunriseSunset{ZonedDateTime}(
+    transit=2023-06-21T13:42:15+02:00,
+    sunrise=2023-06-21T05:18:05+02:00,
+    sunset=2023-06-21T22:06:24+02:00
+)
+```
+
+Find the next sunrise from a specific time in UTC:
+
+```julia
+julia> next_sunrise(obs, DateTime(2023, 6, 21, 12, 30))
+2023-06-22T03:18:19
+```
+
+Find the next sunset in UTC:
+
+```julia
+julia> next_sunset(obs, DateTime(2023, 6, 21, 12, 30))
+2023-06-21T20:06:24
+```
+
 ## Solar positioning algorithms
 
 Here we provide an overview of the solar positioning algorithms currently implemented

docs/src/index.md

@@ -6,14 +6,17 @@ CurrentModule = SolarPosition
 
 ## SolarPosition.jl
 
+[![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://juliaastro.org/SolarPosition/stable/)
+[![Development documentation](https://img.shields.io/badge/docs-dev-blue.svg)](https://juliaastro.org/SolarPosition.jl/dev/)
+
 [![Test workflow status](https://github.com/JuliaAstro/SolarPosition.jl/actions/workflows/Test.yml/badge.svg?branch=main)](https://github.com/JuliaAstro/SolarPosition.jl/actions/workflows/Test.yml?query=branch%3Amain)
 [![Coverage](https://codecov.io/gh/JuliaAstro/SolarPosition.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/JuliaAstro/SolarPosition.jl)
 [![Lint workflow Status](https://github.com/JuliaAstro/SolarPosition.jl/actions/workflows/Lint.yml/badge.svg?branch=main)](https://github.com/JuliaAstro/SolarPosition.jl/actions/workflows/Lint.yml?query=branch%3Amain)
 [![Docs workflow Status](https://github.com/JuliaAstro/SolarPosition.jl/actions/workflows/Docs.yml/badge.svg?branch=main)](https://github.com/JuliaAstro/SolarPosition.jl/actions/workflows/Docs.yml?query=branch%3Amain)
 [![Aqua QA](https://raw.githubusercontent.com/JuliaTesting/Aqua.jl/master/badge.svg)](https://github.com/JuliaTesting/Aqua.jl)
 [![tested with JET.jl](https://img.shields.io/badge/%F0%9F%9B%A9%EF%B8%8F_tested_with-JET.jl-233f9a)](https://github.com/aviatesk/JET.jl)
 
-`SolarPosition.jl` provides a simple, unified interface to a collection of validated solar position
+SolarPosition.jl provides a simple, unified interface to a collection of validated solar position
 algorithms written in pure, performant julia.
 
 Solar positioning algorithms are commonly used to calculate the solar zenith and
@@ -24,32 +27,23 @@ azimuth angles, which are essential for various applications where the sun is im
 - Climate studies
 - Astronomy
 
-## Extensions
-
-SolarPosition.jl provides package extensions for the following use cases:
-
-- **[ModelingToolkit.jl](https://github.com/SciML/ModelingToolkit.jl)**: Integrate solar position calculations into symbolic modeling workflows. Create composable solar energy system models. A [Dyad](https://juliahub.com/products/dyad) component is also provided. See the [ModelingToolkit Extension](guides/modelingtoolkit.md) guide for details.
-
-- **[Makie.jl](https://github.com/MakieOrg/Makie.jl)**: Plotting recipes for solar position visualization with `sunpathplot` and `sunpathpolarplot` functions. See the plotting guide in the [Makie Extension](guides/plotting.md) for details.
-
-- **[OhMyThreads.jl](https://github.com/JuliaFolds2/OhMyThreads.jl)**: Multithreaded solar position computation using task-based parallelism. Provides parallel implementations of [`solar_position!`](@ref) for efficient batch calculations across multiple timestamps. See the [OhMyThreads Extension](guides/parallel.md) guide for details.
-
 ## Acknowledgement
 
-This package is based on the work done by readers in the field of solar photovoltaics
+This package is based on the work done by researchers in the field of solar photovoltaics
 in the packages [solposx](https://github.com/assessingsolar/solposx) and
 [pvlib-python](https://github.com/pvlib/pvlib-python). In particular the positioning and
-refraction methods have been adapted from [solposx](https://github.com/assessingsolar/solposx), while
-the SPA algorithm and the deltat calculation are ported from [pvlib-python](https://github.com/pvlib/pvlib-python). These packages also provide validation data necessary to ensure
+refraction methods have been adapted from [solposx](https://github.com/assessingsolar/solposx),
+while the SPA algorithm and the deltat calculation are ported from [pvlib-python](https://github.com/pvlib/pvlib-python). These packages also provide validation data necessary to ensure
 correctness of the algorithm implementations.
 
 ## Example Usage
 
-```@example
-using SolarPosition, Dates
+```@example srt
+using SolarPosition, Dates, TimeZones
 
 # define observer location (latitude, longitude, altitude in meters)
 obs = Observer(52.35888, 4.88185, 100.0)  # Van Gogh Museum, Amsterdam
+tz = TimeZone("Europe/Brussels")
 
 # a few hours of timestamps
 times = collect(DateTime(2023, 6, 21, 10):Hour(1):DateTime(2023, 6, 21, 15));
@@ -58,6 +52,26 @@ times = collect(DateTime(2023, 6, 21, 10):Hour(1):DateTime(2023, 6, 21, 15));
 positions = solar_position(obs, times)
 ```
 
+### Sunrise and Sunset Calculations
+
+Calculate sunrise, sunset, and solar noon for a specific date with timezone:
+
+```@example srt
+result = transit_sunrise_sunset(obs, ZonedDateTime(2023, 6, 21, tz))
+```
+
+Find the next sunrise from a specific time in UTC:
+
+```@example srt
+next_sunrise(obs, DateTime(2023, 6, 21, 12, 30))
+```
+
+Find the next sunset in UTC:
+
+```@example srt
+next_sunset(obs, DateTime(2023, 6, 21, 12, 30))
+```
+
 ## Solar positioning algorithms
 
 Here we provide an overview of the solar positioning algorithms currently implemented
@@ -85,6 +99,23 @@ Atmospheric refraction correction algorithms available in SolarPosition.jl.
 | [`SG2`](@ref SolarPosition.Refraction.SG2)                         | [Blanc & Wald, 2012](https://doi.org/10.1016/j.solener.2012.07.018)                              | Pressure, Temperature  | ✅     |
 | [`SPARefraction`](@ref SolarPosition.Refraction.SPARefraction)     | [Reda & Andreas, 2004](https://doi.org/10.1016/j.solener.2003.12.003)                            | Pressure, Temperature  | ✅     |
 
+## Extensions
+
+SolarPosition.jl provides optional extensions that are automatically loaded when you
+import the corresponding packages:
+
+| Extension       | Trigger Package                                                       | Features                                          |
+| --------------- | --------------------------------------------------------------------- | ------------------------------------------------- |
+| Makie           | [`Makie.jl`](https://github.com/MakieOrg/Makie.jl)                    | Plotting recipes for solar position visualization |
+| OhMyThreads     | [`OhMyThreads.jl`](https://github.com/JuliaFolds2/OhMyThreads.jl)     | Parallel computation of solar positions           |
+| ModelingToolkit | [`ModelingToolkit.jl`](https://github.com/SciML/ModelingToolkit.jl)   | Symbolic solar position models for simulations    |
+
+!!! note
+    For more details on the extensions, see:
+    - [ModelingToolkit Extension](guides/modelingtoolkit.md)
+    - [Makie Extension](guides/plotting.md)
+    - [OhMyThreads Extension](guides/parallel.md)
+
 ## How to Cite
 
 If you use SolarPosition.jl in your work, please cite using the reference given in [CITATION.cff](https://github.com/JuliaAstro/SolarPosition.jl/blob/main/CITATION.cff).

docs/src/utilities.md

@@ -33,7 +33,7 @@ Gogh museum in Amsterdam on June 21, 2023:
 ```@example utilities
 using SolarPosition, Dates, TimeZones
 
-tz_amsterdam = TimeZone("Europe/Amsterdam", TimeZones.Class(:LEGACY))
+tz_amsterdam = TimeZone("Europe/Brussels")
 obs = Observer(52.35888, 4.88185, 100.0)
 
 # Summer solstice
@@ -62,7 +62,7 @@ println("Next Sunset:  ", next_sunset_time)
 
 ## Plotting the Solar Altitude
 
-To visualize the solar altitude throughout the day, we can use the `solar_position`
+To visualize the solar altitude throughout the day, we can use the [`solar_position`](@ref)
 function to compute the solar positions at regular intervals and plot the results. We
 will make use of [`next_sunrise`](@ref) and [`next_sunset`](@ref) to mark the sunrise
 and sunset times on the plot.
@@ -246,11 +246,6 @@ The utility functions accept three different time input types:
 Here's an example showing the different input types:
 
 ```@example utilities
-using SolarPosition, Dates, TimeZones
-
-obs = Observer(52.35888, 4.88185, 100.0)  # Amsterdam
-tz_amsterdam = TimeZone("Europe/Amsterdam", TimeZones.Class(:LEGACY))
-
 # Using ZonedDateTime (recommended - timezone aware)
 zdt = ZonedDateTime(2023, 6, 21, 12, 0, tz_amsterdam)
 events_zdt = transit_sunrise_sunset(obs, zdt)