Merge pull request #4 from leo-210/docs

Add getting started and example pages

Author: leo-210

docs/examples.md

@@ -0,0 +1,10 @@
+# Example
+
+Here is a list of the different examples by API.
+
+### Geocoding API
+- [Get the current temperature in a city](examples/city_info.html)
+
+### Forecast API
+- [Get the current temperature at a position](examples/current_temperature.html)
+- [Get the hourly forecast for one day at a position](examples/hourly_forecast.html)

docs/examples/city_info.md

@@ -0,0 +1,38 @@
+# Get information on a city or town
+
+This example uses the Geocoding API. For more information, check the 
+`sunny/api/geocoding` module !
+
+```gleam
+import gleam/int
+import gleam/io
+import gleam/option
+import sunny
+import sunny/api/geocoding
+
+pub fn city_info_test() {
+  // Use `new_commercial("<your_api_key>")` if you have a commercial Open-meteo
+  // API access.
+  let sunny = sunny.new()
+
+  let assert Ok(location) =
+    sunny
+    // If the location your searching for isn't the first result, try 
+    // `geocoding.get_locations`
+    |> geocoding.get_first_location(
+      geocoding.params("marseille")
+      // Changing the language can impact the search results.
+      |> geocoding.set_language(geocoding.French),
+    )
+
+  let assert option.Some(population) = location.population
+
+  io.println(
+    location.name
+    <> ", "
+    <> location.country_code
+    <> " has a population of : "
+    <> int.to_string(population),
+  )
+}
+```

docs/examples/current_temperature.md

@@ -0,0 +1,50 @@
+# Get the current temperature at a position
+
+This example uses the Forecast API. For more information, check the 
+`sunny/api/forecast` module !
+
+```gleam
+import gleam/dict
+import gleam/io
+import gleam/option
+import sunny
+import sunny/api/forecast
+import sunny/api/forecast/data
+import sunny/api/forecast/instant
+import sunny/measurement
+import sunny/position
+
+pub fn current_temperature_test() {
+  // Use `new_commercial("<your_api_key>")` if you have a commercial Open-meteo
+  // API access.
+  let sunny = sunny.new()
+
+  // You can get the coordinates of a place using the Geocoding API. See 
+  // `sunny/api/geocoding`, or the `city_info` example.
+  //
+  // Once you have a `Location`, use `geocoding.location_to_position()` to
+  // convert it to a position.
+  let position = position.Position(43.0, 5.0)
+
+  let assert Ok(forecast_result) =
+    sunny
+    |> forecast.get_forecast(
+      forecast.params(position)
+      // All available variables are listed in the `sunny/api/forecast/instant` module.
+      // Daily variables are in `sunny/api/forecast/daily`.
+      |> forecast.set_current([instant.Temperature2m]),
+    )
+
+  let assert option.Some(data.CurrentData(data: data, ..)) =
+    forecast_result.current
+
+  let assert Ok(current_temperature) =
+    data
+    |> dict.get(instant.Temperature2m)
+
+  io.println(
+    "Current temperature : " <> measurement.to_string(current_temperature),
+  )
+}
+```
+

docs/examples/hourly_forecast.md

@@ -0,0 +1,56 @@
+# Get the hourly forecast for the current day at a position
+
+This example uses the Forecast API. For more information, check the 
+`sunny/api/forecast` module !
+
+```gleam
+import birl
+import gleam/float
+import gleam/io
+import gleam/list
+import sunny
+import sunny/api/forecast
+import sunny/api/forecast/data
+import sunny/api/forecast/instant
+import sunny/position
+import sunny/wmo_code
+
+pub fn hourly_forecast_test() {
+  // Use `new_commercial("<your_api_key>")` if you have a commercial Open-meteo
+  // API access.
+  let sunny = sunny.new()
+
+  // You can get the coordinates of a place using the Geocoding API. See 
+  // `sunny/api/geocoding`, or the `city_info` example.
+  //
+  // Once you have a `Location`, use `geocoding.location_to_position()` to
+  // convert it to a position.
+  let position = position.Position(43.0, 5.0)
+
+  let assert Ok(forecast_result) =
+    sunny
+    |> forecast.get_forecast(
+      forecast.params(position)
+      // All available variables are listed in the `sunny/api/forecast/instant`
+      // module.
+      // Daily variables are in `sunny/api/forecast/daily`.
+      |> forecast.set_hourly([instant.WeatherCode])
+      |> forecast.set_forecast_days(1),
+    )
+
+  let assert Ok(hourly_weather) =
+    forecast_result.hourly
+    |> data.range_to_data_list(instant.WeatherCode)
+
+  hourly_weather
+  |> list.each(fn(timed_data) {
+    io.println(
+      birl.to_time_string(timed_data.time)
+      <> " : "
+      // `wmo_code.to_string` translates the `Int` WMOCode to a human-readable
+      // `String`. 
+      <> wmo_code.to_string(float.round(timed_data.data.value)),
+    )
+  })
+}
+```

docs/getting_started.md

@@ -0,0 +1,32 @@
+# Getting started
+
+First, make sure you added the `sunny` package to your gleam project !
+```
+gleam add sunny
+```
+
+To start interacting with the diffent Open-meteo (OM) APIs, you need to create a new sunny client :
+```gleam
+import sunny
+
+pub fn main() {
+  let sunny = sunny.new()
+}
+```
+<details>
+  <summary>If you have a commercial access to Open-meteo</summary>
+```gleam
+  let sunny = sunny.new_commercial("<your_api_key>")
+```
+</details>
+
+## Using the APIs
+
+Now you can start using the other APIs :
+- Forecast API : Get a lot a of diverse data on the current and future weather 
+conditions anywhere you want.
+- Geocoding API : Get information on a city or town. Useful for getting the coordinates of a place, to then get the forecast there.
+
+More APIs will be supported in the future.
+
+You can check the various [examples](examples.html) to get an idea of how to use the APIs.

gleam.toml

@@ -15,3 +15,12 @@ gleam_json = ">= 1.0.1 and < 2.0.0"
 
 [dev-dependencies]
 glacier = ">= 1.1.0 and < 2.0.0"
+
+[documentation]
+pages = [
+  { title = "Getting started", path = "getting_started.html", source = "./docs/getting_started.md" },
+  { title = "Examples", path = "examples.html", source = "./docs/examples.md" },
+  { title = "Example : City informations", path = "examples/city_info.html", source = "./docs/examples/city_info.md" },
+  { title = "Example : Current temperature", path = "examples/current_temperature.html", source = "./docs/examples/current_temperature.md" },
+  { title = "Example : Hourly forecast", path = "examples/hourly_forecast.html", source = "./docs/examples/hourly_forecast.md" },
+]

test/examples/hourly_forecast.gleam

@@ -38,7 +38,7 @@ pub fn hourly_forecast_test() {
 
   hourly_weather
   |> list.each(fn(timed_data) {
-    io.debug(
+    io.println(
       birl.to_time_string(timed_data.time)
       <> " : "
       // `wmo_code.to_string` translates the `Int` WMOCode to a human-readable