Merge branch 'main' into feature/smhi-class-to-match-0.2.0

.github/workflows/github-action-docs.yaml

@@ -1,8 +1,8 @@
 name: Deploy docs to GitHub Pages
 
 on:
-  push:
-    branches: ["main"]
+  release:
+    types: [published]
 
   workflow_dispatch:
 

docs/index.md

@@ -8,13 +8,19 @@ SMHI stands for [Swedish Meteorological and Hydrological Institute](https://www.
 which is a Swedish agency under its parent department: Ministry of Climate and
 Enterprise.
 
-Initially only these four APIs are supported
+Currently, only these four APIs are supported
 
 - Metobs - Meteorological Observations
 - Metfcts - Meteorological Forecasts
 - Mesan - Meteorological Analysis MESAN
 - Strang - Meteorological Analysis STRÅNG (sunshine)
 
+## Examples
+
+You can reach example usage of the different clients
+
+- [example of Metobs use](/ifk-smhi/metobs-example/)
+
 ## Install
 
 ifk-smhi can be installed as
@@ -40,21 +46,31 @@ It will be expanded in future versions.
 Client to fetch data from meteorological observations.
 Use this to access data from _observations_,
 i.e. recorded data from weather stations scattered over north Europe.
+See [example of Metobs use](/ifk-smhi/metobs-example/)
+for details on how to use the client.
 
 ## Metfcts client
 
 Client to fetch data from meteorological forecasts.
 Use this to access data about _forecasts_, i.e. SMHI weather predictions.
+See [example of Metfcts use](/ifk-smhi/metfcts-example/)
+for details on how to use the client.
 
 ## Mesan client
 
 Client to fetch data from meteorological analysis.
 Use this to access the last 24 hour predictions of weather parameters.
 This API is a useful complement to Metobs because the number of weather
 stations are limited.
+See [example of Mesan use](/ifk-smhi/mesan-example/)
+for details on how to use the client.
 
 ## Strang client
 
 Client to fetch data from meteorological analysis of sunshine.
 Use this to access data about _sunshine_,
 i.e. SMHI prediction of sunshine for a given coordinate.
+This API is also a useful complement to Metobs because the number of weather
+stations measureing sunshine are very limited.
+See [example of Strang use](/ifk-smhi/strang-example/)
+for details on how to use the client.

docs/mesan-example.md

@@ -11,7 +11,14 @@ from smhi.mesan import Mesan
 
 client = Mesan()
 client.approved_time
+# approved time object
+
 client.valid_time
+# valid time object
+
+vt = client.valid_time
+vt.valid_time
+# returns a list of valid datetimes
 ```
 
 Notice that `approved_time` is the time when the MESAN analysis was updated.
@@ -26,9 +33,23 @@ To list available parameters, geographic area as polygon and points do
 from smhi.mesan import Mesan
 
 client = Mesan()
-client.parameters
-client.geo_polygon
-client.get_geo_multipoint(2)
+
+parameters = client.parameters
+parameters.parameter
+# list of all parameter codes and their meaning
+
+client.parameter_descriptions
+# mapping of parameter codes from above and a more descriptive meaning
+
+client.parameter_descriptions[parameters.parameter[0].name]
+# descriptive meaning of parameter
+
+geopoly = client.geo_polygon
+geopoly.coordinates
+# polygon of geographic area as a list
+
+geomultipoint = client.get_geo_multipoint(2)
+# all coordinates of value points as a list
 ```
 
 where `get_geo_multipoint` accepts a downsample argument.
@@ -41,13 +62,25 @@ To get data, two methods are available.
 `leveltype`, `level`, `geo` and `downsample` arguments.
 See above to acquire a valid time and parameter.
 
+Note that the date input can be in either `str` or `datetime` formats.
+The API expects times in UTC but the client expects the user to input
+local datetimes. The local datetimes are converted to UTC before an API request
+is performed.
+
 ```python
 from smhi.mesan import Mesan
 
 client = Mesan()
-data = client.get_point(58, 16)
-data = client.get_multipoint(
-    "2022-11-12T23:00:00Z", "t", "hl", 2, False, 2
+
+point = client.get_point(58, 16)
+point.df
+# dataframe of actual data
+
+point.df_info
+# dataframe with information about available parameters
+
+multipoint = client.get_multipoint(
+    "2024-04-1206T16:00:00Z", "t", "hl", 2, 2
 )
 ```
 

docs/metfcts-example.md

@@ -11,7 +11,14 @@ from smhi.metfcts import Metfcts
 
 client = Metfcts()
 client.approved_time
+# approved time object
+
 client.valid_time
+# valid time object
+
+vt = client.valid_time
+vt.valid_time
+# returns a list of valid datetimes
 ```
 
 Notice that `approved_time` is the time when the Metfcts analysis was updated.
@@ -26,9 +33,23 @@ To list available parameters, geographic area as polygon and points do
 from smhi.metfcts import Metfcts
 
 client = Metfcts()
-client.parameters
-client.geo_polygon
-client.get_geo_multipoint(2)
+
+parameters = client.parameters
+parameters.parameter
+# list of all parameter codes and their meaning
+
+client.parameter_descriptions
+# mapping of parameter codes from above and a more descriptive meaning
+
+client.parameter_descriptions[parameters.parameter[0].name]
+# descriptive meaning of parameter
+
+geopoly = client.geo_polygon
+geopoly.coordinates
+# polygon of geographic area as a list
+
+geomultipoint = client.get_geo_multipoint(2)
+# all coordinates of value points as a list
 ```
 
 where `get_geo_multipoint` accepts a downsample argument.
@@ -38,16 +59,28 @@ where `get_geo_multipoint` accepts a downsample argument.
 To get data, two methods are available.
 `get_point` accepts latitude and longitude arguments.
 `get_multipoint` accepts `validtime`, `parameter`,
-`leveltype`, `level`, `downsample` arguments.
+`leveltype`, `level`, `geo` and `downsample` arguments.
 See above to acquire a valid time and parameter.
 
+Note that the date input can be in either `str` or `datetime` formats.
+The API expects times in UTC but the client expects the user to input
+local datetimes. The local datetimes are converted to UTC before an API request
+is performed.
+
 ```python
 from smhi.metfcts import Metfcts
 
 client = Metfcts()
-data = client.get_point(58, 16)
-data = client.get_multipoint(
-    "2022-11-12T23:00:00Z", "t", "hl", 2, 2
+
+point = client.get_point(58, 16)
+point.df
+# dataframe of actual data
+
+point.df_info
+# dataframe with information about available parameters
+
+multipoint = client.get_multipoint(
+    "2024-04-1206T16:00:00Z", "t", "hl", 2, 2
 )
 ```